> [!NOTE]
> Specifying the --path is important because otherwise ember-cli will try to build your vite app, and it will error.

> [!NOTE]
> Specifying the --config-file is important because ember-cli (what backs ember-exam) doesn't know about cjs files.

Version < 3.0.0

Prior to 2.1.0, Ember Exam must be loaded by importing addon-test-support/load.js and calling loadEmberExam:

loadEmberExam();

### Randomization

The random option allows you to randomize the order in which your tests run. You can optionally specify a "seed" value from which to randomize your tests in order to reproduce results. The seed can be any string value. Regardless of whether you specify a seed or not, Ember Exam will log the seed value used for the randomization at the beginning of the test run:

If you use random without specifying a seed, it must be the last argument you pass. Otherwise, Ember Exam will attempt to interpret any following arguments as the seed value. In other words:

_Note: You must be using QUnit version 1.23.0 or greater for this feature to work properly.
Randomization Iterator
Randomization can be helpful for identifying non-atomic or order-dependent tests. To that end, Ember Exam provides an iterator to make it easy to test lots of variations in your test suite order quickly.

This command will build your application once, and then run the test suite with the random option for the specified number of iterations. You can optionally skip the build by using a previous build via the path option:

Finally, you can pass additional options through to the exam command used to run the tests via the options flag:

The options should be a string matching what you would use via the CLI.

Generating Module Metadata File For Test Execution

The --write-module-metadata-file, wmmf as an alias, allows you to generate a module metadata file after a test run. The file provides metadata about the test modules executed.
It creates a json file, module-metadata-<timestamp>.json, which contains an array of elements representing metadata of modules executed by sorted by ascending order:

and it looks something like below:

### Splitting

The split option allows you to specify the number of partitions greater than one to spread your tests across. Ember Exam will then proceed to run the first batch of tests.

The partition option allows you to specify which test group to run after using the split option. It is one-indexed, so if you specify a split of 3, the last group you could run is 3 as well. You can also run multiple partitions, e.g.:

_Note: Ember Exam splits tests by modifying the ember-qunit's TestLoader to bucket each test file into a partition, where each partition has an even number of test files. This makes it possible to have unbalanced partitions. To run your tests with balanced partitions, consider using --load-balance. For more info, see _Test Load Balancing_.

Split Test Parallelization

The parallel option allows you to run your split tests across multiple test pages in parallel in Testem. It will use a separate browser instance for each group of tests. So, if you specify a split of 3, then 3 browser instances will be spawned with the output looking something like:

You can also combine the parallel option with the partition option to split tests, and then recombine partitions into parallel runs. This would, for example, allow you to run tests in multiple CI containers and have each CI container parallelize its list of tests.
For example, if you wanted to run your tests across two containers, but have one of them run twice as many tests as the other, and run them in parallel, you could do this:

Note 1: _Ember Exam will respect the parallel setting of your Testem config file while running tests in parallel. The default value for parallel in Testem is 1, which means you'll need a non-default value to actually see parallel behavior._

Note 2: _Ember Exam sets process.env.EMBER_EXAM_SPLIT_COUNT for convenience. You can use this in your Testem file._

Note 3: _You must be using Testem version 1.5.0 or greater for this feature to work properly._

Filtering
Ember Exam provides options to filter test suites by two types - module path and test file path.

The module-path option allows you to filter module paths by a given value. Module paths are mapped by test files and they are generated during ember build. After the build, tests.js file is created and it resides under <build-directory>/assets. The file is combined of all tests in an application and it has a form of define("<module-path>", others...

The value for module-path can have either string or regular expression, for instance:

The file-path option is to filter tests by test file path. The test file path is a location of the test file in a file system. You can specify file-path to a location of specific test file path or you can use wildcards in paths to target multiple test files.

### Test Load Balancing

The load-balance option allows you to load balance test files against multiple browsers. It will order the test files by test types, e.g. acceptance | integration | unit, and load balance the ordered test files between the browsers dynamically rather than statically.
Note: parallel must be used along with load-balance to specify a number of browser(s)
The load-balance option was added to version 1.1 to address execution performance when running against a large test suite.

Web browsers and the testem server communicate via promise in order to send and receive test file. The promise timeout value is set to 15 seconds, and is configurable by adding asyncTimeout=[timeout] as a querystring param in the test URL or adding to the test_page option in the testem config.
For example, if you specify load-balance and parallel equals 3, then three browser instances will be created and the output will look something like:

You can also specify the split and partition options with load-balance to load a portion of test modules on multiple CI containers.

This command will split test files and load-balance tests from the specified partition across the browsers. For example ember exam --split=2 --partition=1 --parallel=3 --load-balance, the complete list of test files are split into two halves. With the first half of the list load balanced against three browsers. The output will look something like below:

Important information on Load Balancing

The --load-balance option is currently only supported in CI mode and for that reason no-launch cannot be used with load-balance.

You must be using ember-cli version 3.2.0 or greater for load balancing and test failure reproduction features to work properly.

You must be using ember-qunit version 4.1.1 or greater for this feature to work properly.

You must be using qunit version 2.13.0 or greater for this feature to work properly.

##### Test Failure Reproduction
Due to the dynamic nature of the load-balance option, test file execution order can vary between runs. In order to reproduce a past test execution, the execution must be recorded via passing --write-execution-file or --wef, which allows generating a JSON file that enables rerunning the past test execution. The option is only allowed when load-balance is passed.

The file is stored in the root directory and the naming structure is test-execution-<timestamp>.json.
To replay the test execution for particular browser(s), do the following:

replay-execution allows you to specify a path to the json file to run execution against and replay-browser is to specify browser ID(s) to execute.

The command will read test-execution-000000.json and load the list of modules mapped to browserId 1

The above command will read test-execution-000000.json and load the list of modules which is mapped by browser ID #1.

replay-browser can be an array of browser IDs. For instance --replay-browser=1,2 will start two browsers and execute a list of modules which were previously run by browsers #1 and #2.

The command will read test-execution-000000.json and load the list of module mapped to browserId 1 and 2

When replay-browser value is not specified it will execute browserId(s) read from failedBrowser in the test execution file.

The command will read test-execution-000000.json and load the list of modules mapped to browserIds from failedBrowser in the json file.

When replay-browser value is not specified and there is no value for failedBrowser in the json file it will rerun all list of modules.

The command will read test-execution-000000.json and load the list of module mapped to all browserIds when failedBrowser is none in the json file

Important information on --replay-execution and --replay-browser

You must be using ember-cli version 3.2.0 or greater for load-balnce and test failure reproduction features to work properly.

You must be using ember-qunit version 4.1.1 or greater for this feature to work properly.

You must be using qunit version 2.8.0 or greater for this feature to work properly.

Preserve Test Name
When using --split and/or --load-balance the output will look something like:

ember exam --split=2 --partition=1 --parallel=3 --load-balance

However, if you change the amount of parallelization, or randomize across partitions, the output will change for the same test, which may be an issue if you are tracking test insights over time.

ember exam --split=2 --partition=1 --parallel=2 --load-balance

You can add --preserve-test-name to remove the dynamic segments of the output (partition and browser) to ensure the output test names are always the same.

ember exam --split=2 --partition=1 --parallel=3 --load-balance --preserve-test-name

## Advanced Configuration

Ember Exam does its best to allow you to run your test suite in a way that is effective for your individual needs. To that end, there are lots of advanced ways to configure your setup by integrating with other aspects of the Ember testing environment. The following sections will cover a few of the more common scenarios.
Ember Try & CI Integration
Integrating ember-exam with ember-try is remarkably easy. Define a command in your ember-try.js config that leverages the exam command:

Using environmental variables gives you flexibility in how you run your tests. For instance, you could distribute your tests across processes instead of parallelizing them by specifying a PARTITION variable in your process environment and then consuming it like so:

If you are working with Travis CI then you can also easily set up seeded-random runs based on PR numbers. Similar to the following:

if (pr) { command.push(pr); }

module.exports = { command: command.join(' '), // ... };

You can refer to Travis' default environment variables to see what else you could possibly leverage for your test setup.

Test Suite Segmentation
Some test suites like to segment which tests run based on various facets such as type of test, feature being tested, and so on. This can be accomplished by leveraging Testem's ability to have multiple test pages:

You can use this feature in conjunction with Ember Exam's features, which will allow you to segment your test suite but still gain benefits from randomization and splitting.

Exceeding Browser Timeout
If you have a lot of tests you may run into a timeout error, especially in CI environments with constrained resources.

You can work around this by increasing browser_disconnect_timeout in testem.js: