Ember CLI Blueprint Test Helpers

Common errors

• TypeError: (0 , _emberCliBlueprintTestHelpers.setupTestHooks) is not a function

  cause This error typically occurs when `setupTestHooks` is imported or required incorrectly, or when attempting to destructure it from a module that doesn't export it in the expected way.
  fix Ensure you are using the correct CommonJS `require` or ES module `import` syntax for the helper functions. For CommonJS: `const { setupTestHooks } = require('ember-cli-blueprint-test-helpers');` or for ESM: `import { setupTestHooks } from 'ember-cli-blueprint-test-helpers';`.

• AssertionError: expected 'path/to/file.js' to contents 'some content'

  cause This error indicates that an outdated assertion helper `contents` is being used, which was renamed in a previous version of the library.
  fix Replace `contents` with `contain`. The correct assertion syntax is `expect(file('path/to/file.js')).to.contain('some content');`.

• Error: Blueprint tests for apps are not supported. Only addons.

  cause Attempting to run blueprint tests using this library within an Ember application project rather than an Ember addon project, which is an unsupported use case.
  fix Relocate your blueprint tests to an Ember addon project. This library is specifically designed to test blueprints contained within addons.

Warnings

• gotcha This library is specifically designed for and explicitly 'only works for testing blueprints inside addon projects'. Attempting to use it for blueprint tests within an Ember application project will result in unexpected behavior or failures.
  Fix: Ensure that blueprint tests utilizing `ember-cli-blueprint-test-helpers` are exclusively configured and run within the context of an Ember addon project.
• breaking Version `0.12.0` removed 'obsolete test runner and fixtures' and 'obsolete helpers'. This change will break existing tests that relied on these deprecated utilities.
  Fix: Review and update test code to utilize the new helper syntax (introduced in `v0.11.0`) and current testing patterns. Refer to the updated README or source for available helpers.
• breaking In `v0.10.2`, the example assertion method `contents` was renamed to `contains`. Tests using the older `contents` method for `expect(file(...))` assertions will fail.
  Fix: Update assertion calls from `expect(...).to.contents(...)` to `expect(...).to.contain(...)` to match the new helper name.
• gotcha The `EMBER_CLI_MODULE_UNIFICATION` environment variable, crucial for testing Module Unification blueprints, was restored in `v0.19.2` after being implicitly problematic or missing in some previous versions. Tests relying on this variable might have failed or behaved inconsistently in versions prior to `0.19.2` if they expected this variable to be correctly handled.
  Fix: Upgrade to `v0.19.2` or a newer version to ensure consistent and correct behavior when testing blueprints with Module Unification. Consider using the `isModuleUnification: true` option with `emberNew` for explicit MU setup.

Install

• npm install ember-cli-blueprint-test-helpers npm
• yarn add ember-cli-blueprint-test-helpers yarn
• pnpm add ember-cli-blueprint-test-helpers pnpm

Imports

• setupTestHooks
  wrong:

  const setupTestHooks = require('ember-cli-blueprint-test-helpers').setupTestHooks;

  correct:

  import { setupTestHooks } from 'ember-cli-blueprint-test-helpers';

  The `setupTestHooks` function prepares the test context and typically makes other helpers like `emberNew`, `emberGenerate`, `emberDestroy`, and `file` globally available or bound to the Mocha `this` context.
• emberGenerate
  wrong:

  emberGenerate(); // without explicit import after setupTestHooks(this);

  correct:

  import { emberGenerate } from 'ember-cli-blueprint-test-helpers';

  While often available globally after calling `setupTestHooks(this)`, explicit named imports are the recommended practice for clarity in modern JavaScript and TypeScript environments.
• emberGenerateDestroy
  wrong:

  const { emberGenerateDestroy } = require('ember-cli-blueprint-test-helpers/helpers');

  correct:

  import { emberGenerateDestroy } from 'ember-cli-blueprint-test-helpers';

  This helper is available as a named export. While `require('ember-cli-blueprint-test-helpers/helpers')` explicitly exports helpers, the main package export often re-exports these directly.
• file
  wrong:

  expect(file('path/to/file.js')); // No import statement

  correct:

  import { file } from 'ember-cli-blueprint-test-helpers';

  The `file` helper is used to make assertions on the contents and existence of files in the temporary blueprint test environment. It is often implicitly available after `setupTestHooks` but should be explicitly imported for type safety and clarity.

Quickstart

This quickstart demonstrates how to set up blueprint tests using Mocha and Chai, generate and destroy a hypothetical 'my-blueprint', and assert file existence and content. It also shows testing with Module Unification.

import { setupTestHooks, emberNew, emberGenerate, emberDestroy, file } from 'ember-cli-blueprint-test-helpers';
import { expect } from 'chai';

describe('Acceptance: ember generate and destroy my-blueprint', function() {
  // Create and destroy temporary working directories for each test
  setupTestHooks(this);

  it('my-blueprint foo generates and cleans up files', async function() {
    const args = ['my-blueprint', 'foo'];

    // Create a new Ember.js app in the working directory
    await emberNew();

    // Generate the `my-blueprint` blueprint with name `foo`
    await emberGenerate(args);

    // Assert that the files were generated correctly
    expect(file('app/components/foo.js')).to.exist;
    expect(file('app/components/foo.js'))
      .to.contain('import Component from '@glimmer/component';')
      .to.contain('export default class FooComponent extends Component {}');

    // Destroy the `my-blueprint` blueprint with name `foo`
    await emberDestroy(args);

    // Assert that the generated files were destroyed correctly
    expect(file('app/components/foo.js')).to.not.exist;
  });

  it('my-blueprint bar with Module Unification', async function() {
    const args = ['my-blueprint', 'bar'];

    // Create a new Ember.js app with Module Unification structure
    await emberNew({ isModuleUnification: true });

    // Generate and destroy the `my-blueprint` blueprint called `bar`
    await emberGenerateDestroy(args, (fileContents) => {
      // Assertions run between generate and destroy
      expect(fileContents('src/ui/components/bar/component.js')).to.exist;
      expect(fileContents('src/ui/components/bar/component.js'))
        .to.contain('// Module Unification component content');
    });
  });
});