{"id":17217,"library":"ember-cli-blueprint-test-helpers","title":"Ember CLI Blueprint Test Helpers","description":"ember-cli-blueprint-test-helpers provides a dedicated suite of testing utilities for `ember-cli` blueprint authors. It enables comprehensive testing of blueprint generation and destruction logic by mocking the `ember-cli` environment, allowing developers to simulate `ember generate` and `ember destroy` commands within a controlled context. The current stable version is `0.19.2`, with releases occurring periodically to address bugs and introduce minor enhancements, rather than a fixed cadence. A key differentiator is its specialized focus on blueprint testing within Ember addon projects, providing helpers like `setupTestHooks`, `emberNew`, `emberGenerate`, `emberDestroy`, and `emberGenerateDestroy` to streamline the assertion process for generated and removed files, including support for Module Unification setups. This package is crucial for ensuring the correctness and stability of `ember-cli` blueprints.","status":"active","version":"0.19.2","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli/ember-cli-blueprint-test-helpers","tags":["javascript","ember-addon","ember"],"install":[{"cmd":"npm install ember-cli-blueprint-test-helpers","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-blueprint-test-helpers","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-blueprint-test-helpers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal dependency added in v0.12.1, likely for promise-based operations within the helpers.","package":"rsvp"},{"reason":"Internal dependency added in v0.10.0, likely for file system operations like finding blueprint files.","package":"glob"},{"reason":"Commonly used assertion library in conjunction with this package for blueprint tests, often exposed via `require('ember-cli-blueprint-test-helpers/chai')`.","package":"chai"},{"reason":"Typically used as the test runner for `node-tests` where blueprint tests are executed. Configured in `package.json` scripts.","package":"mocha"}],"imports":[{"note":"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.","wrong":"const setupTestHooks = require('ember-cli-blueprint-test-helpers').setupTestHooks;","symbol":"setupTestHooks","correct":"import { setupTestHooks } from 'ember-cli-blueprint-test-helpers';"},{"note":"While often available globally after calling `setupTestHooks(this)`, explicit named imports are the recommended practice for clarity in modern JavaScript and TypeScript environments.","wrong":"emberGenerate(); // without explicit import after setupTestHooks(this);","symbol":"emberGenerate","correct":"import { emberGenerate } from 'ember-cli-blueprint-test-helpers';"},{"note":"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.","wrong":"const { emberGenerateDestroy } = require('ember-cli-blueprint-test-helpers/helpers');","symbol":"emberGenerateDestroy","correct":"import { emberGenerateDestroy } from 'ember-cli-blueprint-test-helpers';"},{"note":"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.","wrong":"expect(file('path/to/file.js')); // No import statement","symbol":"file","correct":"import { file } from 'ember-cli-blueprint-test-helpers';"}],"quickstart":{"code":"import { setupTestHooks, emberNew, emberGenerate, emberDestroy, file } from 'ember-cli-blueprint-test-helpers';\nimport { expect } from 'chai';\n\ndescribe('Acceptance: ember generate and destroy my-blueprint', function() {\n  // Create and destroy temporary working directories for each test\n  setupTestHooks(this);\n\n  it('my-blueprint foo generates and cleans up files', async function() {\n    const args = ['my-blueprint', 'foo'];\n\n    // Create a new Ember.js app in the working directory\n    await emberNew();\n\n    // Generate the `my-blueprint` blueprint with name `foo`\n    await emberGenerate(args);\n\n    // Assert that the files were generated correctly\n    expect(file('app/components/foo.js')).to.exist;\n    expect(file('app/components/foo.js'))\n      .to.contain('import Component from '@glimmer/component';')\n      .to.contain('export default class FooComponent extends Component {}');\n\n    // Destroy the `my-blueprint` blueprint with name `foo`\n    await emberDestroy(args);\n\n    // Assert that the generated files were destroyed correctly\n    expect(file('app/components/foo.js')).to.not.exist;\n  });\n\n  it('my-blueprint bar with Module Unification', async function() {\n    const args = ['my-blueprint', 'bar'];\n\n    // Create a new Ember.js app with Module Unification structure\n    await emberNew({ isModuleUnification: true });\n\n    // Generate and destroy the `my-blueprint` blueprint called `bar`\n    await emberGenerateDestroy(args, (fileContents) => {\n      // Assertions run between generate and destroy\n      expect(fileContents('src/ui/components/bar/component.js')).to.exist;\n      expect(fileContents('src/ui/components/bar/component.js'))\n        .to.contain('// Module Unification component content');\n    });\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure that blueprint tests utilizing `ember-cli-blueprint-test-helpers` are exclusively configured and run within the context of an Ember addon project.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Update assertion calls from `expect(...).to.contents(...)` to `expect(...).to.contain(...)` to match the new helper name.","message":"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.","severity":"breaking","affected_versions":">=0.10.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">0.13.0 <0.19.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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';`.","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.","error":"TypeError: (0 , _emberCliBlueprintTestHelpers.setupTestHooks) is not a function"},{"fix":"Replace `contents` with `contain`. The correct assertion syntax is `expect(file('path/to/file.js')).to.contain('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.","error":"AssertionError: expected 'path/to/file.js' to contents 'some content'"},{"fix":"Relocate your blueprint tests to an Ember addon project. This library is specifically designed to test blueprints contained within 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.","error":"Error: Blueprint tests for apps are not supported. Only addons."}],"ecosystem":"npm","meta_description":null}