This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the changelog.

Airtap 4 is a modular rewrite that supports concurrent local browsers, headless testing with Playwright, starting Sauce Labs from your local machine & from GitHub Actions, and live reload on any browser.

Browsers have been abstracted away into abstract-browser and browser-provider. The purpose of the latter is to discover browsers on a particular platform or remote service and expose them to Airtap. Coming from Airtap 3, which was primarily meant to run Sauce Labs browsers, you'll want to install the airtap-sauce provider and add it to airtap.yml:

npm install airtap-sauce --save-dev

providers:
  - airtap-sauce

You can now run tests on headless Playwright browsers, by including the airtap-playwright provider in your configuration. Or locally installed browsers with airtap-system. Or include multiple providers and let Airtap find the best matching browser:

providers:
  - airtap-playwright
  - airtap-system

browsers:
  - name: ff
    version: 78

For details, please see the README.

The airtap-sauce provider includes the Sauce Connect tunnel, which means Airtap can now start Sauce browsers from your local machine and from GitHub Actions. The tunnel-id / tunnel_id option has been removed.

Only localhost and airtap.local are routed through the tunnel, with SSL bumping disabled. In addition, Airtap only starts a tunnel if it is testing browsers that require one. If you are using the Travis Sauce Connect addon you can (choose to) keep doing so and Airtap will skip starting a tunnel itself.

The --electron and --local flags have been removed in favor of providers. The relevant providers to check out are airtap-electron, airtap-default and airtap-manual. The airtap-default provider behaves like --local --open did: it opens the default browser. While the airtap-manual provider behaves like --local did.

You may recall that the --electron and --local flags also overrode any browsers defined in airtap.yml. To achieve that same exclusive behavior, use a preset which selectively overrides your root configuration:

providers:
  - airtap-sauce

browsers:
  - name: chrome

presets:
  local:
    providers:
      - airtap-system

airtap test.js # runs chrome in sauce labs
airtap -p local test.js # runs local chrome

providers:
  - airtap-sauce
  - airtap-default

browsers:
  - name: chrome

presets:
  local:
    browsers:
      - name: default

airtap test.js # runs chrome in sauce labs
airtap -p local test.js # runs local default browser

On any browser, Airtap now exits by default after the tests complete. To allow repeated runs like before, pass the new --live flag. This keeps Airtap running and doesn't close the browser. When browserify errors, Airtap exits unless --live. When you make changes to your test files during a test, browsers are automatically reloaded.

As a general rule, Airtap 4 defaults to a small set of browsers. Browsers are deduplicated by properties you did not explicitly match on. Each entry in browsers will match exactly one browser, unless multiple versions are specified. If your specified browser has 0 matches, an error is thrown.

The sauce-browsers dependency has been replaced with airtap-sauce-browsers and airtap-match-browsers. This led to a few breaking changes:

TAP output is now parsed in the backend instead of the frontend, with tap-parser upgraded from v5 to v10. Browsers send console logs to the backend over WebSockets, or HTTP in older browsers. Support of IE < 11 has been restored. Stack traces embedded in TAP no longer utilize source maps; we may restore this functionality in a future release.

A number of options have been renamed:

A few sauce-only options have moved to airtap-sauce:

Various options have been removed:

Lastly, Airtap no longer reads airtap.config.js.

Dropped support of node < 10.

Upgraded browserify from 13.x to 16.x, which ends support of IE < 11. If you need IE 9-10, either stick with airtap@1 or follow the workaround described in #171.

First stable release. No breaking changes since 0.1.0. Intended as release line for users needing IE9-10 support; the next major release will only support IE11+ (#171).

The --local [port] option has been split into two options: --local and --port <port>. Previously, if you didn't specify a port and --local was the last flag, you had to do --local -- test.js. This is no longer the case. If you do want to specify a port, you must now do --local --port 8000.

The sauce_connect option has been removed, as Sauce Connect is the default and only tunnel. You can remove sauce_connect from .airtap.yml and --sauce-connect from command line arguments.

If you used this option to specify a custom tunnel identifier for Sauce Connect (e.g. --sauce-connect <id>), you must now do --tunnel-id <id> on the command line or tunnel_id: <id> in .airtap.yml.

npm rm zuul --save-dev
npm install airtap --save-dev

Rename calls to the zuul binary accordingly. If you had this in your package.json:

"scripts": {
  "test": "zuul test.js"
}

Change it to:

"scripts": {
  "test": "airtap test.js"
}

Rename .zuul.yml to .airtap.yml. If you also have a ~/.zuulrc for Sauce Labs credentials, rename it to ~/.airtaprc.

Frameworks other than tap and tape are no longer supported. You can remove the --ui option from your command line arguments and from .airtap.yml.

We removed support of localtunnel and ngrok in favor of Sauce Connect. Delete any tunnel, disable-tunnel and tunnel-host options from your command line arguments and .airtap.yml. Instead add:

sauce_connect: true

Then enable the Sauce Connect addon in your .travis.yml:

addons:
  sauce_connect: true

It is not yet possible to start Sauce Labs tests from your local machine, unless you manually run the Sauce Connect binary.

Safari and Edge never use a proxy for requests to localhost, which means they are not routed through the Sauce Connect tunnel. To support these two browsers, first add the hosts addon to your .travis.yml:

addons:
  sauce_connect: true
  hosts:
    - airtap.local

This makes the airtap.local hostname resolve to 127.0.0.1. You can use any hostname you want. Then add this hostname to your .airtap.yml:

loopback: airtap.local

Now Airtap will open the tests at airtap.local instead of localhost and Safari and Edge properly route requests through Sauce Connect. Happy testing!