playwright-test

Run mocha, zora, uvu, tape and benchmark.js scripts inside real browsers with playwright.

Install

1pnpm install playwright-test

Usage

1playwright-test [files] [options]
2# or
3pw-test [files] [options]
4

Options

1Description
2    Run mocha, zora, uvu, tape and benchmark.js scripts inside real browsers with `playwright` and in Node.
3
4  Usage
5    $ playwright-test [files] [options]
6
7  Options
8    -r, --runner       Test runner. Options: mocha, tape, zora, uvu, none, taps and benchmark. Internal runners are autodetected by default. It also accepts a path to a module or a module ID that exports a `playwrightTestRunner` object.
9    -b, --browser      Browser to run tests. Options: chromium, firefox, webkit.  (default chromium)
10    -m, --mode         Run mode. Options: main, worker and node.  (default main)
11    -d, --debug        Debug mode, keeps browser window open.  (default false)
12    -w, --watch        Watch files for changes and re-run tests.
13    -i, --incognito    Use incognito window to run tests.  (default false)
14    -e, --extension    Use extension background_page to run tests.  (default false)
15    --cov              Enable code coverage in istanbul format. Outputs '.nyc_output/coverage-pw.json'.  (default false)
16    --report-dir       Where to output code coverage in instanbul format.  (default .nyc_output)
17    --before           Path to a script to be loaded on a separate tab before the main script.
18    --sw               Path to a script to be loaded in a service worker.
19    --assets           Folder with assets to be served by the http server.  (default process.cwd())
20    --cwd              Current directory.  (default /Users/hd/code/playwright-test)
21    --extensions       File extensions allowed in the bundle.  (default js,cjs,mjs,ts,tsx)
22    --config           Path to the config file
23    -v, --version      Displays current version
24    -h, --help         Displays this message
25
26
27  Examples
28    $ playwright-test test.js --runner tape
29    $ playwright-test test --debug
30    $ playwright-test "test/**/*.spec.js" --browser webkit --mode worker --incognito --debug
31
32    $ playwright-test bench.js --runner benchmark
33    # Uses benchmark.js to run your benchmark see playwright-test/mocks/benchmark.js for an example.
34
35    $ playwright-test test --cov && npx nyc report --reporter=html
36    # Enable code coverage in istanbul format which can be used by nyc.
37
38    $ playwright-test "test/**/*.spec.js" --debug --before ./mocks/before.js
39    # Run a script in a separate tab. Check ./mocks/before.js for an example.
40    # Important: You need to call `self.PW_TEST.beforeEnd()` to start the main script.
41
42  Runner Options
43    All arguments passed to the cli not listed above will be fowarded to the runner.
44    $ playwright-test test.js --runner mocha --bail --grep 'should fail'
45
46    To send a `false` flag use --no-bail.
47    Check https://mochajs.org/api/mocha for `mocha` options or `npx mocha --help`.
48
49  Notes
50    DEBUG env var filtering for 'debug' package logging will work as expected.
51    $ DEBUG:app playwright-test test.js
52
53    Do not let your shell expand globs, always wrap them.
54    $ playwright-test "test/**" GOOD
55    $ playwright-test test/** BAD

Client

This client package exposes the playwright-test options and some Playwright browser context methods to be used in tests.

1import * as Client from 'playwright-test/client'
2
3it('should setoffline', async () => {
4  if (Client.mode === 'main' && Client.options.extension === false) {
5    globalThis.addEventListener('offline', () => {
6      console.log('offlineee')
7    })
8    await Client.context.setOffline(true)
9    equal(navigator.onLine, false)
10    await Client.context.setOffline(false)
11    equal(navigator.onLine, true)
12  }
13})
14
15it('should geolocation', async () => {
16  if (Client.mode === 'main') {
17    const deferred = pdefer()
18    await Client.context.setGeolocation({
19      latitude: 59.95,
20      longitude: 30.316_67,
21    })
22    await Client.context.grantPermissions(['geolocation'])
23
24    navigator.geolocation.getCurrentPosition((position) => {
25      deferred.resolve(position)
26    })
27
28    const position = (await deferred.promise) as GeolocationPosition
29    equal(position.coords.latitude, 59.95)
30  }
31})

Flow control

All test runners support automatic flow control, which means you don't need to call special function or trigger any event in your tests to stop the run. The none runner does not support flow control.

To manually stop the run you can use process.exit:

1process.exit(0) // stops the run and exits with success
2process.exit(1) // stops the run and exits with failure

Custom test runner

You can define a custom test runner by passing a path to a file or a node module id that exports an object called playwrightTestRunner that implements the TestRunner interface.

1
2$ playwright-test test.js --runner ./my-runner.js
3# or
4$ playwright-test test.js --runner my-runner
5

You can also just define you test runner in the config file.

1// playwright-test.config.js
2/** @type {import('../src/runner.js').RunnerOptions} */
3const config = {
4  testRunner: {
5    compileRuntime: (options, paths) => {
6      return `
7import mocha from 'mocha/mocha.js'
8mocha.setup({
9    reporter: 'spec',
10    timeout: 5000,
11    ui: 'bdd',
12})
13
14${paths.map((url) => `await import('${url}')`).join('\n')}
15
16  mocha
17    .run((f) =>{
18      process.exit(f)
19    })
20        `
21    },
22  },
23}
24
25export default config

1export interface TestRunner {
2  /**
3   * Module ID name used to import the test runner runtime.
4   * Used in auto detection of the test runner.
5   */
6  moduleId: string
7  /**
8   * Options made available to the compiled runtime.
9   * This is useful to pass options to the test runner.
10   *
11   * @example
12   * ```js
13   * const options = JSON.parse(process.env.PW_OPTIONS)
14   * const testRunnerOptions = options.testRunner.options
15   * ```
16   */
17  options?: unknown
18  /**
19   * Esbuild config for the test runner
20   */
21  buildConfig?: BuildOptions
22  /**
23   * Compile runtime entry point for esbuild
24   *
25   * @param options - Runner options
26   * @param testPaths - Test paths
27   * @returns
28   */
29  compileRuntime: (options: RunnerOptions, testPaths: string[]) => string
30}

Config

The config file needs to be commonjs for now, so if your package is pure ESM you need to use .cjs extension.

Configuration can be done with cli flags or config files.

1package.json, // using property `pw-test` or `playwright-test`
2.playwright-testrc.json,
3.playwright-testrc.js,
4.playwright-testrc.cjs,
5playwright-test.config.js,
6playwright-test.config.cjs,
7.pw-testrc.json,
8.pw-testrc.js,
9.pw-testrc.cjs,
10pw-test.config.js,
11pw-test.config.cjs,
12.config/playwright-testrc.json
13.config/playwright-testrc.js
14.config/playwright-testrc.cjs
15.config/pw-testrc.json
16.config/pw-testrc.js
17.config/pw-testrc.cjs

The config type can be imported from the entrypoint.

1/** @type {import('playwright-test').RunnerOptions} */
2const config = {
3  // ...
4}
5
6export default config

The config file can also export a function that receives the cli options as argument.

1/** @type {import('playwright-test').ConfigFn} */
2function buildConfig(cliOptions) {
3  return {
4    buildConfig: {
5      bundle: cliOptions.mode !== 'node',
6    },
7  }
8}
9
10export default buildConfig

Interface

1export interface RunnerOptions {
2  input?: string[]
3  testRunner: TestRunner
4  cwd: string
5  extensions: string
6  browser: 'chromium' | 'firefox' | 'webkit'
7  debug: boolean
8  mode: 'main' | 'worker' | 'node'
9  incognito: boolean
10  extension: boolean
11  assets: string
12  before?: string
13  sw?: string
14  cov: boolean
15  reportDir: string
16  buildConfig: BuildOptions
17  buildSWConfig: BuildOptions
18  browserContextOptions?: BrowserContextOptions
19  beforeTests: (opts: RunnerOptions) => Promise<unknown>
20  afterTests: (
21    opts: RunnerOptions,
22    beforeTestsOutput: unknown
23  ) => Promise<unknown>
24}

Run in CI

Check our CI config .github/workflows/main.yml and the playwright Github Action

License

MIT © Hugo Dias