babel-plugin-ember-test-metadata

babel-plugin-ember-test-metadata

A Babel plugin for Ember apps that adds a test's file path to test metadata available through @ember/test-helpers.

Why use this plugin

A test file's path can enable downstream consumers of test results to process, and potentially associate a specific test failure to a file path. This can assist with the analysis of test infrastructure, specifically where identifying ownership over a test file is useful or required.

This Babel plugin transforms a test so that its file path is added to @ember/test-helpers test metadata, where other utilities can subsequently read that data.

Installation

npm install babel-plugin-ember-test-metadata --save-dev

# or

yarn add babel-plugin-ember-test-metadata -D

Usage

This plugin needs to be configured in your ember-cli-build.js file by adding it your babel's plugins array:

'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function (defaults) {
  let app = new EmberApp(defaults, {
    babel: {
      plugins: [
        [
          require.resolve('babel-plugin-ember-test-metadata'),
          {
            enabled: !!process.env.BABEL_TEST_METADATA,
            packageName: defaults.project.pkg.name,
          },
        ],
      ],
    },
  });

  // additional configuration

  return app.toTree();
};

If you're using Embroider instead of Ember CLI, you need to tell the plugin how to process the file paths:

'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function (defaults) {
  let app = new EmberApp(defaults, {
    babel: {
      plugins: [
        [
          require.resolve('babel-plugin-ember-test-metadata'),
          {
            enabled: !!process.env.BABEL_TEST_METADATA,
            packageName: defaults.project.pkg.name,
            isUsingEmbroider: true,
          },
        ],
      ],
    },
  });

  // additional configuration

  return app.toTree();
};

Set the environment variable BABEL_TEST_METADATA=true to enable the plugin to perform its transformations.

You can additionally pass in a projectRoot relative path to the options to accommodate more complex project structures like workspaces.

'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function (defaults) {
  let app = new EmberApp(defaults, {
    babel: {
      plugins: [
        [
          require.resolve('babel-plugin-ember-test-metadata'),
          {
            enabled: !!process.env.BABEL_TEST_METADATA,
            packageName: defaults.project.pkg.name,
            packageRoot: '../..',
          },
        ],
      ],
    },
  });

  // additional configuration

  return app.toTree();
};

You can also pass a custom function to normalize the test file path.

/**
  * Get a normalized file path
  * @param {string} options.packageName the name of the package as specified in Babel plugin options
  * @param {boolean} options.isUsingEmbroider whether building using Embroider as specified in Babel plugin options
  * @param {boolean} options.projectRoot custom relative path to the project's root as specified in Babel plugin options
  * @param {string} options.filename the absolute perceived path of the file being visited
  * @param {string} options.root the absolute root project path as seen on disk
}
*/
module.exports = function customNormalizedFilePath(options) {
    // Custom normalization
}

'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function (defaults) {

  let app = new EmberApp(defaults, {
    babel: {
      plugins: [
        [
          require.resolve('babel-plugin-ember-test-metadata'),
          {
            enabled: !!process.env.BABEL_TEST_METADATA,
            packageName: defaults.project.pkg.name,
            packageRoot: '../..',
            getCustomNormalizedFilePath: require.resolve('path/to/your/customNormalizedFilePath/function'),
          },
        ],
      ],
    },
  });

  // additional configuration

  return app.toTree();
};