ember-cli-yadda

Ember-cli-yadda

This Ember CLI addon facilitates writing BDD tests in the Gherkin language and executing them against your Ember app.

@mschinis (Micheal Schinis) Did a great talk at @emberlondon BDD approach with ember using ember-cli-yadda.

It uses the yadda library to parse and run your feature files, and integrates into your Ember test setup using either ember-qunit or ember-mocha.

The following describes the use of ember-cli-yadda >= v0.4.0 which works only with the latest modern Ember testing APIs, as laid out in the RFCs 232 and 268.

For the older APIs use v0.3.x and have a look at our Legacy Guide.

Compatibility

• Ember.js v3.20 or above
• Ember CLI v3.20 or above
• Node.js v12 or above
• ember-auto-import v2 or Embroider

Due to the way yadda is written, you need to add some custom webpack config options when using Embroider!

Installation

Installing ember-cli-yadda is a breeze. All you need to do is run the following command in your project directory.

ember install ember-cli-yadda

This adds the following files:

/tests/acceptance/steps/steps.js
/tests/integration/steps/steps.js
/tests/unit/steps/steps.js
/tests/helpers/yadda-annotations.js

You may specify the version of yadda by adding it in package.json and running npm install.

Upgrading

See the Release Notes.

Usage

The following describes the specific features and Ember integration points of ember-cli-yadda. For general documentation on how to write yadda-based tests please consult the Yadda User Guide.

Creating feature files

This ember-cli addon provides you with a blueprint with which you can create feature files:

ember g feature [feature title] --type=[acceptance|integration|unit]

Acceptance tests

For acceptance tests you can omit the --type option. So you can use ember g feature [feature title] which generates a feature file for your acceptance tests and a step definition.

For example:

ember g feature make-a-feature

This will generate the following files in your project directory:

/tests/acceptance/steps/make-a-feature-steps.js
/tests/acceptance/make-a-feature.feature

Integration or unit tests

To create an integration or unit test, you can use ember g feature [feature title] --type=integration for an integration test, or --type=unit for a unit test. This generates a feature and step definition file where you can write your tests.

For example:

ember g feature make-a-feature --type=unit

This will generate the following files in your project directory:

/tests/unit/steps/make-a-feature-steps.js
/tests/unit/make-a-feature.feature

Writing tests

Let's take this example of an acceptance test feature:

@setupApplicationTest
Feature: bananas rot

  Scenario: bananas rot faster when next to apples
    Given I have a bananas
    And it's next to an apples
    When left together for a while
    Then the banana rots

The @setupApplicationTest annotation will setup all scenarios of this feature as application tests, using the setupApplicationTest() function provided by either ember-qunit or ember-mocha. See the Annotations section below for more information on how to setup your tests.

Because we probably have more features about bananas, we add the Given I have bananas to the global steps file: /tests/acceptance/steps.js

import yadda from 'yadda';
import { visit } from '@ember/test-helpers';

export default function(assert) {
  return yadda.localisation.default.library()
    .given("I have bananas", async function() {
      await visit("/bananas");
    });
}

Notice that the preferable way to handle asynchronous steps like the one above is to use async/ await. But you can also explicitly return a promise or use a next() callback.

The fact that "it's next to apples" is probably unique to this Feature so we'll add it to the feature specific step definitions in /tests/acceptance/steps/bananas-rot-feature-steps.js. That will look like this:

import steps from './steps';

// step definitions that are shared between features should be moved to the
// tests/accptance/steps/steps.js file

export default function(assert) {
  return steps(assert)
    .given('it\'s next to apples', function() {
      let apples = this.element.querySelectorAll('.apple');
      assert.ok(apples.length > 0)
    })
    .when('left together for a while', function(next) {
      // bananas rot really quickly next to apples.
      setTimeout(next, 1000);
    })
    .then('the banana rots', function () {
      let banana = this.element.querySelector('.banana');
      assert.ok(banana.classList.contains('rotten'));
    });
}

Important information

Scope and helpers

ember-cli-yadda passes the original scope down to each step definition. This means that you have access to the same context (like this.element or this.owner) and helpers from @ember/test-helpers (like click()), as you did when writing a normal test in QUnit/Mocha.

Sharing variables between steps

You can easily share variables between your steps, by either creating a new variable outside your step chain, or by storing the values in this.ctx in each step.

For Example:

  import steps from './steps';

  // Variable outside step chain
  let something = '';

  export default function(assert) {
    return steps(assert)
      .given('I add something to the context', function() {
        // Assign 'hello' to the variable outside the step chain
        something = 'hello';
        // Assign 'there' to a new variable in `this.ctx`
        this.ctx.something = 'there';
        assert.ok(true, this.step);
      })
      .then('it should be there in the next step', function() {
        // Do an assertion to check that 'there' has been passed correctly
        // to the next step
        assert.equal(this.ctx.something, 'there', this.step);
      })
      .then('external variable should be there in the next step', function(){
        // Assert that the external variable still holds the information
        // we set in the first step
        assert.equal(something,'hello',this.step);
      });
  }

Annotations

You already saw the use of the @setupApplicationTest annotation in the example feature file above. Yadda's support for annotations can be used to customize the way tests are run.

The implementation for the way certain annotations affect your tests lives in the tests/yadda-annotations.js file. The addon installs this file with a default implementation as described below, but you can freely customize it at your will.

Skipping tests

See the Contributing guide for details. You can skip tests by adding the @ignore annotation above the Scenario or Feature.

Test suites

You can set ENV.annotations to an array of annotations (either statically or e.g. by assigning them from an environment variable like process.env.ANNOTATIONS). This will then run only those Features or Scenarios that have one of these annotations assigned.

Setup tests

For each of the setup functions already known from ember-qunit or ember-mocha, there exists a corresponding annotation to setup your Feature/Scenario accordingly:

• @setupTest for (unit) tests requiring the DI container of Ember to be set up
• @setupRenderingTest for (integration) tests allowing you to call render, e.g. for component tests
• @setupApplicationTest for (acceptance) tests requiring the whole application to be booted

Customization

You can customize how annotations are handled in your app's tests/yadda-annotations.js file, e.g. to add support for additional annotations, or extend the existing ones. This module has to export these hooks, that are called by this addon's test runner:

• runFeature: called for each feature. If you return a function, this will be called to run the feature, instead of the default implementation.
• runScenario: similar to runFeature, but called for each scenario.
• setupFeature: called for each feature to setup the test environment. You can call QUnit's or Mocha's beforeEach and afterEach functions here to add custom setup/teardown work.
• setupScenario: similar to setupFeature, but called for each scenario.

Have a look at the existing implementation and the comments present in your tests/yadda-annotations.js file!

Here is an example to extend the defaul implementation of the @setupApplicationTest annotation to also call the setupMirage() function provided by ember-cli-mirage to setup the Mirage server:

import setupMirage from 'ember-cli-mirage/test-support/setup-mirage';

// your existing tests/yadda-annotations.js file...

function setupYaddaTest(annotations) {
  if (annotations.setupapplicationtest) { // lower case!
    return function(hooks) {
      setupApplicationTest(hooks);
      setupMirage(hooks);
    }
  }
  // ...
}

Yadda Configuration

If you need to set Yadda configuration, add the following to ember-cli-build.js:

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {

    'ember-cli-yadda': {
      yaddaOptions: { // passed through to yadda parseFeature()
        language: 'Polish', // converted to Yadda.localisation.Polish
        leftPlaceholderChar: '<',
        rightPlaceholderChar: '>'
      }

    }
  });

See yadda FeatureParser for yadda options.

Inner workings

This ember addon registers a preprocessor that parses .feature / .spec / .specification files using yadda and generates a -test.js file in the apropriate test folder. It also adds a little loader helper /tests/helpers/yadda.js because yadda does not define an amd module.

The addon also adds ES6 modules /tests/[type]/steps/steps you can extend in feature specific step definitions. Any shared step definitions should be moved to these file or included there, depending on the type of test you are running. Feature specific step definitions reside in /tests/[type]/steps/. The generated feature test js files import a /tests/[type]/steps/[feature title]-steps module, where type can either be acceptance, integration or unit.

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Changelog

v0.7.0 (2021-10-19)

:boom: Breaking Change

• #246 Update to ember-auto-import v2 (@simonihmig)
• #248 Update Ember to 3.28, drop support for 3.16 (@simonihmig)
• #247 Drop node 10 support (@simonihmig)

:rocket: Enhancement

• #246 Update to ember-auto-import v2 (@simonihmig)
• #248 Update Ember to 3.28, drop support for 3.16 (@simonihmig)

Committers: 2

• Simon Ihmig (@simonihmig)
• @dependabot-preview[bot]