# e2e Packs a library's build, installs the tarball into the project that tests it, and runs that project's suites on Node's test runner, handing each the tarball's path in the environment as HF_E2E_TARBALL so a suite can install it into a consumer outside the workspace. ```json { "e2e": { "executor": "@hyperfrontend/workspace:e2e", "dependsOn": ["^build"], "options": { "formats": [ "cjs", "esm", "browser", { "name": "consumer", "specs": ["src/consumer.spec.ts"], "timeoutMs": 300000 } ] } } } ``` | Option | What it does | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--packageDir` | The built package; defaults to the build output of the library this project implicitly depends on | | `--testDir` | The e2e project; defaults to the project the task runs in | | `--formats` | What to run: the built-in [formats](https://www.hyperfrontend.dev/docs/libraries/workspace/executors/e2e/#api-E2eFormat) cjs, esm and browser run the conventional spec files, and an object names a suite of the project's own with its specs, a timeout, whether it needs the DOM and what it runs serially on | | `--skipInstall` | Reuses an install already in place | | `--cleanupTarball` | Removes the tarball afterwards; defaults to true | The browser suite preloads a DOM for the IIFE and UMD bundles, which needs jsdom installed beside [`@hyperfrontend/testing`](https://www.hyperfrontend.dev/docs/libraries/testing.md). ## API Reference ### Functions #### e2eExecutor ```typescript function e2eExecutor(options: E2eExecutorOptions, context: ExecutorContext): Promise ``` E2E executor for testing package build outputs. Workflow: 1. Run `npm pack` in the dist directory to create a tarball 2. Install the tarball in the E2E test project 3. Run each configured format's suites on the node test runner (cjs, esm, browser, and the suites the project declares) 4. Optionally cleanup the tarball **Parameters** | Name | Type | Description | | --- | --- | --- | | `options` | `E2eExecutorOptions` | Configuration for test directory, formats, and cleanup behavior | | `context` | `ExecutorContext` | The workspace, the project and the target the task runs on | **Returns** `Promise`: A promise resolving to an object indicating success or failure **Example: An e2e project's target, the library found through `implicitDependencies`** ```json { "name": "e2e-core", "implicitDependencies": ["lib-core"], "targets": { "e2e": { "executor": "@hyperfrontend/workspace:e2e", "dependsOn": ["^build"], "options": { "formats": ["cjs", "esm", { "name": "consumer", "specs": ["src/consumer.spec.ts"], "timeoutMs": 120000 }] } } } } ``` `npx hf run e2e-core:e2e` packs `dist/libs/core`, installs the tarball into `e2e/core`, and runs the three suites. #### formatRun ```typescript function formatRun(format: E2eFormat, platform: string): FormatRun ``` How a format of the target's options runs. **Parameters** | Name | Type | Description | | --- | --- | --- | | `format` | `E2eFormat` | A built-in format's name, or a suite the project declares itself | | `platform` | `string` | The platform the run happens on | **Returns** `FormatRun`: The run, or undefined for a name that is no built-in format **Example: A built-in format and a declared suite** ```typescript formatRun('browser', 'linux') // => { name: 'browser', candidates: ['src/iife.spec.ts', 'src/umd.spec.ts'], dom: true, timeoutMs: 30000, serial: false } formatRun({ name: 'consumer', specs: ['src/consumer.spec.ts'], timeoutMs: 120000, serialOn: ['win32'] }, 'win32') // => { name: 'consumer', candidates: ['src/consumer.spec.ts'], dom: false, timeoutMs: 120000, serial: true } ``` #### libraryUnderTest ```typescript function libraryUnderTest(projects: Readonly>, project: ProjectConfiguration): ProjectConfiguration ``` The library an e2e project tests: the first project it implicitly depends on that builds. **Parameters** | Name | Type | Description | | --- | --- | --- | | `projects` | `Readonly>` | Every project's configuration by name | | `project` | `ProjectConfiguration` | The e2e project | **Returns** `ProjectConfiguration`: The library's configuration, or undefined when the project depends on none that builds **Example: The implicit dependency that builds names the library** ```typescript libraryUnderTest(context.projects, context.projects['e2e-core']) // => context.projects['lib-core'] when e2e-core lists implicitDependencies: ['lib-core'] and lib-core has a build target ``` #### testingAliases ```typescript function testingAliases(workspaceRoot: string): Record ``` The path aliases of the test runtime, as the workspace declares them. A run that replaces the workspace aliases outright, so a packed tarball resolves from a test project's `node_modules`, still has to reach the runtime by name where the workspace serves it from source. **Parameters** | Name | Type | Description | | --- | --- | --- | | `workspaceRoot` | `string` | The workspace root, absolute | **Returns** `Record`: The runtime's aliases and nothing else; none in a workspace that installs the runtime **Example: Only the runtime's aliases survive** ```typescript testingAliases(root) // => { '@hyperfrontend/testing': ['libs/testing/src/index.ts'], '@hyperfrontend/testing/*': ['libs/testing/src/*'] } in the workspace that develops the runtime // => {} in a workspace that installs it ``` ### Interfaces #### E2eExecutorOptions Options for the e2e executor. **Properties** | Name | Type | Description | | --- | --- | --- | | `packageDir?` | `string` | Path to built package directory relative to workspace root | | `testDir?` | `string` | Path to E2E test project directory relative to workspace root | | `formats?` | `E2eFormat[]` | Output formats to test | | `skipInstall?` | `boolean` | Skip npm pack and install step | | `cleanupTarball?` | `boolean` | Remove tarball after installation | #### E2eFormatEntry A suite of an e2e project that the built-in formats do not name. **Properties** | Name | Type | Description | | --- | --- | --- | | `name` | `string` | The name the run is reported under | | `specs` | `string[]` | The spec files it runs, relative to the test project | | `timeoutMs?` | `number` | Per-test timeout in milliseconds; 30000 when unset | | `dom?` | `boolean` | Whether the run needs the DOM preload | | `serialOn?` | `string[]` | The platforms (`process.platform` values) on which the suites run one at a time | ### Types #### E2eFormat A format of the e2e target: a built-in name or a suite the project declares. ```typescript type E2eFormat = "cjs" | "esm" | "browser" | E2eFormatEntry ``` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/executors/e2e/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/executors/e2e.md Documentation index: https://www.hyperfrontend.dev/llms.txt