{"id":15411,"library":"yeoman-test","title":"Yeoman Generator Testing Utilities","description":"Yeoman-test provides a comprehensive suite of utilities designed for unit testing Yeoman generators. It simplifies the process of testing generator logic, file system modifications, and user interactions. The current stable version is 11.3.1. Releases occur frequently, often in conjunction with updates to core Yeoman ecosystem packages like `@yeoman/adapter`, `yeoman-environment`, and `yeoman-generator`, ensuring compatibility and leveraging new features. Key differentiators include its tight integration with Yeoman's `mem-fs` virtual file system, enabling robust assertions on generated files and content without touching the actual disk. It facilitates setting up temporary test directories, simulating command-line arguments and user prompts, and asserting file creation, content, and deletion. It also offers mechanisms for mocking composed generators, which is crucial for testing complex generator flows. The library aims to provide a controlled, isolated environment for predictable and reliable generator testing.","status":"active","version":"11.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/yeoman/yeoman-test","tags":["javascript","yeoman","unit test","typescript"],"install":[{"cmd":"npm install yeoman-test","lang":"bash","label":"npm"},{"cmd":"yarn add yeoman-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add yeoman-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the adapter interface for Yeoman environments, essential for generator execution context.","package":"@yeoman/adapter","optional":false},{"reason":"Defines common types and interfaces used across the Yeoman ecosystem.","package":"@yeoman/types","optional":false},{"reason":"Underpins the virtual file system used by Yeoman generators for file operations and assertions.","package":"mem-fs","optional":false},{"reason":"The core environment in which Yeoman generators run; required for instantiating and running generators.","package":"yeoman-environment","optional":false},{"reason":"The base class for Yeoman generators; required to define and test generator instances.","package":"yeoman-generator","optional":false}],"imports":[{"note":"Since v11.0.0, Yeoman-test primarily targets ESM environments (Node.js >=20). The `helpers` object is exported as the default export, while `result` is a named export containing the last RunResult instance.","wrong":"const helpers = require('yeoman-test');","symbol":"helpers","correct":"import helpers, { result } from 'yeoman-test';"},{"note":"The `run` method is a static method on the `helpers` default export object. It is not a top-level named export itself.","wrong":"import { run } from 'yeoman-test';","symbol":"run","correct":"import helpers from 'yeoman-test'; await helpers.run('namespace');"},{"note":"When using TypeScript, import `RunResult` as a type for explicit type annotations on the `result` object or other test outcomes.","symbol":"RunResult (type)","correct":"import { type RunResult } from 'yeoman-test';"}],"quickstart":{"code":"import helpers, { result } from 'yeoman-test';\nimport assert from 'assert';\n\ndescribe('generator test suite', () => {\n  // Define a dummy generator namespace or point to a local generator path\n  const generatorNamespace = 'my-generator:app';\n\n  beforeEach(async () => {\n    // Ensure your generator and its dependencies are installed:\n    // npm install --save-dev yeoman-generator yeoman-environment\n    // npm install --save-dev yeoman-test\n    // This will run the generator in a temporary directory\n    await helpers\n      .run(generatorNamespace)\n      .withOptions({ skipInstall: true, someOption: 'value' })\n      .withPrompts({ name: 'my-project', features: ['featureA'] });\n  });\n\n  it('creates a project directory and a specific file', () => {\n    // Assertions using the global result object from the last run\n    result.assertNoFileContent('package.json', /\"private\": true/);\n    result.assertFile('my-project/package.json');\n    result.assertFileContent('my-project/package.json', /\"name\": \"my-project\"/);\n    result.assertJsonFileContent('my-project/package.json', { dependencies: { lodash: '^4.0.0' } });\n  });\n\n  it('can create additional generators in the same context', async () => {\n    // Use result.create to run another generator within the same temporary directory\n    await result.create('another-generator:sub').run();\n    result.assertFile('my-project/src/sub-feature.js');\n  });\n\n  it('handles composed generators correctly', async () => {\n    // Mock a composed generator to verify interaction without running its full logic\n    await helpers.run('my-generator:app').withMockedGenerators(['composed:feature']);\n    assert(result.mockedGenerators['composed:feature'].calledOnce);\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to set up, run, and assert outcomes of a Yeoman generator test using `yeoman-test`. It covers running generators with options and prompts, asserting file system changes, and mocking composed generators."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 20.6.1 or higher. Alternatively, pin `yeoman-test` to a `10.x` version using `npm install --save-dev yeoman-test@^10`.","message":"Version 11.0.0 of `yeoman-test` raises the minimum required Node.js version to `^20.6.1 || >=22`. Projects running on older Node.js versions will need to upgrade their Node.js environment or remain on `yeoman-test` v10.x. This change also implies an shift towards ESM-first module resolution.","severity":"breaking","affected_versions":">=11.0.0"},{"fix":"Always check the `peerDependencies` in `package.json` for `yeoman-test` to ensure compatibility with your installed `yeoman-environment` and `yeoman-generator` versions. Update all Yeoman-related packages together when upgrading `yeoman-test`.","message":"`yeoman-test` is tightly coupled with `yeoman-environment` and `yeoman-generator`. Major version bumps in `yeoman-test` (e.g., v11) often coincide with breaking changes or new peer dependency requirements for these core Yeoman packages. Incompatible versions can lead to runtime errors or unexpected behavior.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your test files use ESM `import` syntax. Configure your `package.json` with `\"type\": \"module\"` for your test directory or use a `.mjs` extension for test files. If using a test runner, ensure it's configured to run tests as ESM.","message":"With the shift to modern Node.js versions (v20+) and the project's move towards ESM, using CommonJS `require()` statements for `yeoman-test` might lead to `ERR_REQUIRE_ESM` errors, especially when integrating with test runners that default to CommonJS.","severity":"gotcha","affected_versions":">=11.0.0"},{"fix":"For sequential or independent runs, ensure assertions are made immediately after each `await helpers.run(...)` or `await result.create(...).run()` call. For complex scenarios, consider wrapping runs in local variables if the global `result` object's behavior causes confusion.","message":"The `result` object, imported as a named export, holds the `RunResult` instance of the *last* executed `helpers.run()` command. If you perform multiple `helpers.run()` or `result.create().run()` calls within the same test block or `beforeEach`, `result` will only reflect the final one, potentially leading to incorrect assertions if you expect an earlier run's state.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Convert your test files to use ES Module `import` syntax (`import helpers from 'yeoman-test';`). Ensure your project or test files are configured for ESM (e.g., `\"type\": \"module\"` in `package.json` or `.mjs` file extensions).","cause":"Attempting to use `require('yeoman-test')` in a CommonJS context when `yeoman-test` v11+ is an ES Module.","error":"ERR_REQUIRE_ESM: require() of ES Module .../node_modules/yeoman-test/lib/index.js from ... not supported."},{"fix":"Ensure that `await helpers.run(...)` has completed before attempting to use `result` for assertions. Verify `import { result } from 'yeoman-test';` is present and correctly scoped.","cause":"The `result` object or its methods are accessed before a generator has been successfully run, or `result` was not properly imported.","error":"TypeError: Cannot read properties of undefined (reading 'assertFile')"},{"fix":"Install or upgrade `yeoman-environment` to a compatible version as specified in `yeoman-test`'s `peerDependencies`. For `yeoman-test@11`, this typically means `yeoman-environment@^4.0.0 || ^5.0.0-beta.0 || ^6.0.0`.","cause":"Missing `yeoman-environment` peer dependency or an incompatible version installed, preventing `yeoman-test` from initializing the generator environment.","error":"Error: You don't have yeoman-environment installed. Try npm install yeoman-environment."}],"ecosystem":"npm"}