Ember Try

4.0.0 · active · verified Tue Apr 21

Ember Try is an Ember CLI addon designed to facilitate testing Ember applications and addons against various versions of their dependencies, particularly `ember` and `ember-data`. The current stable version is 4.0.0, released in March 2025. It allows developers to define "scenarios" that modify `package.json` dependencies, install them, run a specified command (usually `ember test`), and then revert the changes. This is crucial for maintaining compatibility across different Ember ecosystem versions. Its primary differentiators include deep integration with `ember-cli`, a declarative configuration for scenarios, and commands like `ember try:each` for iterative testing and `ember try:one` for specific scenario runs. It also supports automatic scenario generation based on `semver` ranges in `package.json` via its `versionCompatibility` feature, making it a cornerstone for robust Ember ecosystem testing. The release cadence appears tied to major Ember CLI or Node.js ecosystem shifts, with major versions released periodically to address breaking changes and new features.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'ui')
```
cause The `project` instance is no longer passed to the `ember-try` config function in v4.0.0, leading to errors if you attempt to access properties of a non-existent `project` argument.

fix Update `config/ember-try.js` to remove the `project` argument from the exported function signature. For example, change `module.exports = function(project) { ... }` to `module.exports = function() { ... }`.
```
Error: Node.js v14.x is no longer supported by ember-try. Please upgrade to Node.js v18.x or higher.
```
cause Attempting to run `ember-try` v3.0.0 or higher with an unsupported Node.js version (e.g., Node.js 14).

fix Upgrade your Node.js environment to version 18 or higher (e.g., using `nvm install 18 && nvm use 18`).
```
Bower is not supported for scenarios. Please use npm or pnpm.
```
cause Your `ember-try` configuration attempts to define scenarios with Bower dependencies after `ember-try` v2.0.0, which removed Bower support.

fix Migrate all dependency declarations within your `ember-try` scenarios from Bower to npm or pnpm. `ember-try` exclusively manages Node package manager dependencies.
```
My application builds with unexpected dependencies in CI after `ember try:each`.
```
cause A previous `ember try:one` or `ember try:each` command was run with `--skip-cleanup=true`, and the CI environment was not reset before a build step.

fix Ensure `ember try:reset` is explicitly run after any command using `--skip-cleanup=true`, or configure your CI to always perform a clean checkout for build steps to prevent dependency pollution.

Warnings

breaking The `ember-cli project` instance is no longer passed as an argument to the configuration function exported by `config/ember-try.js`.
Fix: Update your `config/ember-try.js` file to remove the `project` argument from the exported function signature (e.g., `module.exports = function() { ... }`).
breaking When using pnpm, scripts are ignored by default in scenarios to prevent unintended side effects.
Fix: If your scenarios rely on specific pnpm lifecycle scripts, you may need to explicitly configure them not to be ignored or adjust your workflow accordingly.
breaking Node.js 14 support has been dropped.
Fix: Ensure your development and CI environments are running Node.js version 18 or higher. The `engines.node` field specifies `>= 18`.
breaking Support for scenarios involving Bower dependencies has been dropped.
Fix: Migrate all dependency management in your `ember-try` scenarios from Bower to npm or pnpm. `ember-try` now exclusively manages Node package manager dependencies.
gotcha Using the `--skip-cleanup=true` option with `ember try:one` or `ember try:each` can leave your project in a modified state with the last tested dependencies installed.
Fix: Always manually run `ember try:reset` after using `--skip-cleanup=true` if you need to restore your project to its original state. Avoid this option before building or deploying if you expect original dependencies.

Install

npm install ember-try npm
yarn add ember-try yarn
pnpm add ember-try pnpm

Imports

default export (config function)

wrong:

// config/ember-try.js
import { scenarios } from 'ember-try'; // Incorrect; configuration is a CommonJS module export.

correct:

// config/ember-try.js
module.exports = function(/* app */) {
  return {
    scenarios: [
      {
        name: 'ember-lts-4.4',
        npm: {
          devDependencies: {
            'ember-source': '~4.4.0'
          }
        }
      },
      {
        name: 'ember-beta',
        npm: {
          devDependencies: {
            'ember-source': 'beta'
          }
        }
      }
    ]
  };
};

Configuration is typically defined by exporting a function from `config/ember-try.js`. Since v4.0.0, the `project` instance is no longer passed as an argument to this function.

versionCompatibility (package.json)

wrong:

// package.json
{
  "ember-addon": {
    "versionCompatibility": "^3.28.0" // Not a valid object structure for defining compatibility
  }
}

correct:

// package.json
{
  "ember-addon": {
    "versionCompatibility": {
      "ember": ">=3.28.0 <5.0.0"
    }
  }
}

This is a declarative configuration within `package.json` for auto-generating scenarios based on semver ranges, not a direct JavaScript import.

CLI Commands
```
ember try:each
ember try:one ember-beta --- ember test
ember try:reset
```
The primary interaction with `ember-try` is through `ember` CLI commands, which are made available after addon installation. There are no direct JavaScript imports for these commands.

Quickstart

This quickstart demonstrates how to install `ember-try`, configure a `config/ember-try.js` file with basic scenarios for different Ember versions (default, release, beta, canary), and then execute tests across all defined scenarios using the `ember try:each` command. This setup is common for CI environments.

// First, install ember-try in your Ember CLI project:
ember install ember-try

// This will typically create or update 'config/ember-try.js'.
// Modify 'config/ember-try.js' to define your testing scenarios:
module.exports = function(/* app */) {
  return {
    useVersionCompatibility: true, // Auto-generate scenarios from package.json if desired
    scenarios: [
      {
        name: 'ember-default',
        npm: {
          devDependencies: {} // Uses dependencies defined in your project's package.json
        }
      },
      {
        name: 'ember-release',
        npm: {
          devDependencies: {
            'ember-source': 'release' // Test against the latest stable Ember release
          }
        }
      },
      {
        name: 'ember-beta',
        npm: {
          devDependencies: {
            'ember-source': 'beta' // Test against the Ember beta channel
          }
        },
        allowedToFail: true // Beta/Canary scenarios can be configured to fail without blocking CI
      },
      {
        name: 'ember-canary',
        npm: {
          devDependencies: {
            'ember-source': 'canary' // Test against the Ember canary channel
          }
        },
        allowedToFail: true
      }
    ]
  };
};

// Then, run the `ember try:each` command to execute tests for all scenarios:
ember try:each

view raw JSON →