tapout

The easiest way to run tests in a browser from the command line. Just pipe some JS into this command. A spiritual successor to tape-run.

Contents

• Featuring
• Install
• Use
  • window.testsFinished
  • CI
  • Generate HTML reports
  • -b, --browser
  • -t, --timeout
  • -r, --reporter
• Example Tests
  • Tests

This uses playwright under the hood.

Usage: tapout [options]
            
Options:
  -t, --timeout <ms>    Timeout in milliseconds (default: 10000)
  -b, --browser <name>  Browser to use: chromium, firefox, webkit, edge (default: chromium)
  -r, --reporter <name> Output format: tap, html (default: tap)
  --outdir <path>       Output directory for HTML reports (default: current directory)
  --outfile <name>      Output filename for HTML reports (default: index.html)
  -h, --help           Show this help message

Examples:
  cat test.js | tapout --timeout 5000
  cat test.js | tapout --browser firefox
  cat test.js | tapout -b webkit -t 3000
  cat test.js | tapout --browser edge
  cat test.js | tapout --reporter html
  cat test.js | tapout --reporter html --outdir ./reports
  cat test.js | tapout --reporter html --outfile my-test-results.html
Copy

Featuring

• Cross-browser testing: Run tests in Chrome, Firefox, Safari (WebKit), or Edge
• Smart timeout handling: Respects custom timeouts with intelligent auto-finish behavior
• Comprehensive error detection: Automatically catches unhandled promise rejections, uncaught exceptions, and console errors
• Beautiful HTML reports: Generate responsive HTML reports perfect for CI/CD or sharing
• TAP compatible: Standard TAP output works with any TAP formatter
• Zero configuration: Just pipe JavaScript into this command
• CI/CD friendly: Proper exit codes and error detection

Install

npm i -D @substrate-system/tapout
Copy

Use

Pipe some Javascript to this command.

cat ./test/index.js | npx tapout
Copy

Use shell redirection

npx esbuild --bundle ./test/index.ts | npx tapout | npx tap-spec
Copy

window.testsFinished

The test browser will automatically close within few seconds of no activity.

To explicitly end the tests, set a property on window.

import { test } from '@substrate-system/tapzero'

test('example test', (t) => {
  t.ok(true)
})

test('all done', () => {
  // This will cause the tests to exit immediately.
  // @ts-expect-error tests
  window.testsFinished = true
})
Copy

CI

After npm install, you will need to do an npx playwright install.

For example, in Github CI,

# ...

    - name: npm install, build
      run: |
        npm install
        npm run build --if-present
        npm run lint
        npx playwright install --with-deps
      env:
        CI: true

# ...
Copy

Generate HTML reports

By default writes to stdout.

cat ./test/index.js | npx tapout --reporter html > index.html
open index.html  # View the generated report
Copy

HTML Summary

• --reporter html with no other options -> output HTML to stdout
• --reporter html --outfile filename.html -> save to filename.html in current directory
• --reporter html --outdir ./reports -> save to ./reports/index.html
• --reporter html --outdir ./reports --outfile custom.html -> save to ./reports/custom.html

-b, --browser

Pass in the name of a browser to use. Default is Chrome.

Possibilities are chromium, firefox, webkit, or edge.

-t, --timeout

Pass in a different timeout value. The default is 10 seconds.

The timeout respects the auto-finish behavior:

• With default timeout (no -t flag): Auto-finish triggers after a short delay (1-2 seconds) when no test activity is detected
• With custom timeout (using -t): Auto-finish uses 80% of the specified timeout, giving tests more time to complete naturally

cat test.js | npx tapout --timeout 5000
Copy

Error Detection: tapout automatically detects and reports test failures from:

• Unhandled promise rejections
• Uncaught exceptions
• Console error messages with common error patterns
• TAP "not ok" results

Tests will exit with code 1 if any errors are detected, making it perfect for CI/CD pipelines.

-r, --reporter

Choose the output format. Default is TAP.

Available reporters:

• tap - TAP output (default) - Standard Test Anything Protocol format
• html - Generate an HTML report file with beautiful, responsive design

# Generate HTML report
cat test.js | npx tapout --reporter html

# Generate HTML and output to stdout
cat test.js | npx tapout --reporter html > my-report.html

# Use TAP output (default)
cat test.js | npx tapout

# Customize output location
cat test.js | npx tapout --reporter html --outdir ./reports
cat test.js | npx tapout --reporter html --outfile my-test-results.html
cat test.js | npx tapout --reporter html --outdir ./reports --outfile custom-report.html
Copy

The HTML reporter generates an index.html file by default with:

• Test summary with pass/fail counts and percentages
• Individual test results with status indicators
• Browser and timing information

Output Control:

• --outdir <path> - Specify where to save the HTML report (default: current directory)
• --outfile <name> - Specify the filename for the HTML report (default: index.html)
• If neither --outdir nor --outfile is specified, HTML output is sent to stdout

GitHub Pages Integration: The generated HTML file is self-contained and can be easily hosted on GitHub Pages or any static hosting service. Simply commit the HTML file to your repository.

# Example CI workflow
npm test 2>&1 | npx tapout --reporter html --outfile test-results.html
git add test-results.html
git commit -m "Update test results"
git push
Copy

Example Tests

Write tests for the browser environment.

// test/index.ts
import { test } from '@substrate-system/tapzero'

test('example', t => {
    t.ok(document.body, 'should find a body tag')
})

test('all done', t => {
  // @ts-expect-error explicitly end
  window.testsFinished = true
})
Copy

Run the tests on the command line.

npx esbuild ./test/index.ts | npx tapout
Copy

Tests

See the test/ directory.

npm test
Copy

# HTML reporter examples  
npm run test:simple -- --reporter html     # Generate HTML report
npm run test:complex -- --reporter html    # Complex test HTML report
Copy