@hyperfrontend/workspace/executors/e2e

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.

{
  "e2e": {
    "executor": "@hyperfrontend/workspace:e2e",
    "dependsOn": ["^build"],
    "options": {
      "formats": [
        "cjs",
        "esm",
        "browser",
        {
          "name": "consumer",
          "specs": ["src/consumer.spec.ts"],
          "timeoutMs": 300000
        }
      ]
    }
  }
}
OptionWhat it does
--packageDirThe built package; defaults to the build output of the library this project implicitly depends on
--testDirThe e2e project; defaults to the project the task runs in
--formatsWhat to run: the built-in formats 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
--skipInstallReuses an install already in place
--cleanupTarballRemoves 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.

API Reference§

ƒ Functions

§function

e2eExecutor(options: E2eExecutorOptions, context: ExecutorContext): Promise<ExecutorResult>

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
NameTypeDescription
§options
E2eExecutorOptionsConfiguration for test directory, formats, and cleanup behavior
§context
ExecutorContextThe workspace, the project and the target the task runs on
Returns
Promise<ExecutorResult>
A promise resolving to an object indicating success or failure
Example

An e2e project's target, the library found through `implicitDependencies`

{
  "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.
§function

formatRun(format: E2eFormat, platform: string): FormatRun

How a format of the target's options runs.
Parameters
NameTypeDescription
§format
E2eFormatA built-in format's name, or a suite the project declares itself
§platform
stringThe 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

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 }
§function

libraryUnderTest(projects: Readonly<Record<string, ProjectConfiguration>>, project: ProjectConfiguration): ProjectConfiguration

The library an e2e project tests: the first project it implicitly depends on that builds.
Parameters
NameTypeDescription
§projects
Readonly<Record<string, ProjectConfiguration>>Every project's configuration by name
§project
ProjectConfigurationThe 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

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
§function

testingAliases(workspaceRoot: string): Record<string, unknown>

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
NameTypeDescription
§workspaceRoot
stringThe workspace root, absolute
Returns
Record<string, unknown>
The runtime's aliases and nothing else; none in a workspace that installs the runtime
Example

Only the runtime's aliases survive

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

§interface

E2eExecutorOptions

Options for the e2e executor.
Properties
§packageDir?:stringPath to built package directory relative to workspace root
§testDir?:stringPath to E2E test project directory relative to workspace root
§formats?:E2eFormat[]Output formats to test
§skipInstall?:booleanSkip npm pack and install step
§cleanupTarball?:booleanRemove tarball after installation
§interface

E2eFormatEntry

A suite of an e2e project that the built-in formats do not name.
Properties
§name:stringThe name the run is reported under
§specs:string[]The spec files it runs, relative to the test project
§timeoutMs?:numberPer-test timeout in milliseconds; 30000 when unset
§dom?:booleanWhether the run needs the DOM preload
§serialOn?:string[]The platforms (process.platform values) on which the suites run one at a time

◆ Types

§type

E2eFormat

A format of the e2e target: a built-in name or a suite the project declares.
type E2eFormat = "cjs" | "esm" | "browser" | E2eFormatEntry