ember-testem

Backward- and forward-compatible testing for Ember projects

Why?

Until now, testing Ember apps and addons required ember-cli, a monolith package that is written in JavaScript and has less relevance in v2 apps and v2 addons. Production projects may be at risk because tools like ember-exam and @percy/ember are built on ember-cli.

ember-testem aims to show that:

• The fix is minimal, backward-, and forward-compatible (apps with strict resolver, apps without ember-cli).
• We can keep using qunit and testem. No need to switch to another test framework and rewrite tests.
• It works with battle-tested packages like @embroider/try, @percy/ember, ember-a11y-testing, ember-qunit, ember-test-selectors, miragejs, and qunit-dom.

Quickstart

[!TIP]

From the root of your Ember app or addon, run install-ember-testem to set up ember-testem.

pnpx install-ember-testem

1. Install ember-testem as a development dependency. The package provides an executable named ember-test.

pnpm add -D ember-testem

You can uninstall testem if it is listed in package.json.

2. Configure testem in testem.{mjs,mts}.

export default {
  browser_args: {
    Chrome: {
      ci: [
        // --no-sandbox is needed when running Chrome inside a container
        process.env['CI'] ? '--no-sandbox' : null,
        '--headless',
        '--disable-dev-shm-usage',
        '--disable-software-rasterizer',
        '--mute-audio',
        '--remote-debugging-port=0',
        '--window-size=1440,900',
      ].filter(Boolean),
    },
  },
  browser_start_timeout: 120,
  disable_watching: true,
  launch_in_ci: ['Chrome'],
  launch_in_dev: ['Chrome'],
  test_page: 'tests/index.html?hidepassed&nolint',
};

3. Update the test script in package.json so that it builds the test app, then runs the app (the tests).

{
  "scripts": {
    "build": "..."
+     "build:test": "...",
-     "test": "ember test"
+     "test": "pnpm build:test && ember-test"
+     "test:watch": "concurrently \"pnpm build:test --watch\" && \"pnpm ember-test --server\" --names build,test"
  },
  "devDependencies": {
    "concurrently": "...",
+     "ember-testem": "..."
  }
}

Note, test:watch may encounter race conditions. Once the build is complete, refresh the test browser to see the latest results.

See my-v1-addon for an example.

{
  "scripts": {
    "build": "ember build --environment production",
    "build:test": "ember build --environment test"
  }
}

See my-v1-app for an example.

{
  "scripts": {
    "build": "ember build --environment production",
    "build:test": "ember build --environment test"
  }
}

See my-v2-addon for an example.

In general, I recommend creating a test app as a separate package (using workspaces). This way, you can separate dependencies for source code and testing (avoid past issues with v1 addons). You would set up ember-testem by following the steps for v2 apps.

If you still want to create the test app in the same package, you will need to install and configure additional dependencies. You can use install-ember-testem to get started.

{
  "scripts": {
    "build": "rollup --config",
    "build:test": "NODE_ENV=development vite build --config vite.test.config.mts --mode development"
  }
}

See my-v2-app for an example.

{
  "scripts": {
    "build": "vite build",
    "build:test": "NODE_ENV=development vite build --config vite.test.config.mts --mode development"
  }
}

/* vite.test.config.mts */
import { defineConfig } from 'vite';

import baseConfiguration from './vite.config.mts';

export default defineConfig({
  ...baseConfiguration,
  build: {
    minify: false,
    sourcemap: true,
  },
});

Arguments

Pass --server (-s) to launch a browser. This may be useful for debugging (e.g. with debugger or await this.pauseTest()) and re-running the tests after a code change (don't forget to pass --watch to build:test).

ember-test --server

The --module (-m) option allows you to select a module—a group of tests inside a module().

ember-test --module "Integration | Component | ui/form/input"

The --filter (-f) is more versatile. You can provide a keyword to match against the modules and test descriptions. A test description is what appears in test().

ember-test --filter integration
ember-test --filter ui/form
# Exclude acceptance tests
ember-test --filter \!acceptance

By default, ember-testem assumes dist to be the path to the test build.

Pass --path to indicate otherwise. This may be useful if you want to create the production and test builds in different locations.

ember-test --path dist-for-testing

By default, ember-testem runs tests on port 7357.

Pass --port to pick a different port. You can pass 0 to pick any available port (useful for testing multiple projects in parallel).

ember-test --port 0

Pass --random to randomize the order of tests. This helps you guarantee that your tests are independent of one another.

ember-test --random

You can also pass a seed to run tests in a particular random order.

ember-test --random gflqlwrm59j

[!NOTE]

ember-testem provides a limited API on purpose.

For ember-cli options like --host, --launch, --query, --reporter, --ssl, --ssl-cert, --ssl-key, --test-page, --testem-debug), configure testem in testem.{mjs,mts} instead.

Compatibility

• Node.js v22 or above

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.