yeoman-test 7.3.0 → 7.4.0

package/README.md

@@ -25,6 +25,8 @@ $ npm install --save-dev yeoman-generator@xxx yeoman-environment@xxx
 Usage:
 
 ```js
+import helpers from 'yeoman-test';
+
 describe('generator test', () => {
   describe('test', () => {
     let runResult;
@@ -36,12 +38,22 @@ describe('generator test', () => {
           {}                       // environment options
         )
         [.cd(dir)]                  // runs the test inside a non temporary dir
-        [.doInDir(dir => {})        // prepares the test dir
+        [.onTargetDirectory(dir => {})        // prepares the test dir
         [.withGenerators([])]       // registers additional generators
         [.withLookups({})]          // runs Environment lookups
         [.withOptions({})]          // passes options to the generator
         [.withLocalConfig({})]      // sets the generator config as soon as it is instantiated
         [.withAnswers()]            // simulates the prompt answers
+        [.withMockedGenerators(['namespace', ...])]      // adds a mocked generator to the namespaces
+        [.withFiles({
+          'foo.txt': 'bar',
+          'test.json', { content: true },
+        })]                         // add files to mem-fs
+        [.withYoRc({ 'generator-foo': { bar: {} } })]    // add config to .yo-rc.json
+        [.withYoRcConfig('generator-foo.bar', { : {} })] // same as above
+        [.commitFiles()]            // commit mem-fs files to disk
+        [.onGenerator(gen => {})]   // do something with the generator
+        [.onEnvironment(env => {})] // do something with the environment
         [.build(runContext => {     // instantiates Environment/Generator
           [runContext.env...]       // does something with the environment
           [runContext.generator...] // does something with the generator
@@ -51,6 +63,7 @@ describe('generator test', () => {
     );
     afterEach(() => {
       if (runResult) {
+        // Optional if context is executed at a temporary folder
         runResult.restore();
       }
     });
@@ -68,6 +81,46 @@ describe('generator test', () => {
 });
 ```
 
+Convenience last RunResult instance:
+
+```js
+import helpers, { result } from 'yeoman-test';
+
+describe('generator test', () => {
+  before(() => helpers.run('namespace'));
+  it('test', () => {
+    result.assert...;
+  });
+});
+```
+
+Generator compose:
+
+```js
+import assert from 'assert';
+import helpers, { result } from 'yeoman-test';
+
+describe('my-gen', () => {
+  before(() => helpers.run('my-gen').withMockedGenerator(['composed-gen']));
+  it('should compose with composed-gen', () => {
+    assert(result.mockedGenerators['composed-gen'].calledOnce);
+  });
+});
+```
+
+Generic test folder:
+
+```js
+import helpers, { result } from 'yeoman-test';
+
+describe('generic test', () => {
+  before(() => helpers.prepareTemporaryDir());
+  it('test', () => {
+    result.assert...;
+  });
+});
+```
+
 [See our api documentation](https://yeoman.github.io/yeoman-test) for latest yeoman-test release.
 
 [See our api documentation](https://yeoman.github.io/yeoman-test/5.0.1) for yeoman-test 5.0.1. Use 5.x for yeoman-environment 2.x support.

package/dist/helpers.d.ts

@@ -4,8 +4,7 @@ import type { GeneratorOptions } from 'yeoman-generator';
 import type { Options, createEnv } from 'yeoman-environment';
 import type { SinonSpiedInstance } from 'sinon';
 import { type DummyPromptOptions } from './adapter.js';
-import RunContext from './run-context.js';
-import type { RunContextSettings } from './run-context.js';
+import RunContext, { BasicRunContext, type RunContextSettings } from './run-context.js';
 /**
  * Dependencies can be path (autodiscovery) or an array [<generator>, <name>]
  */
@@ -144,6 +143,11 @@ export declare class YeomanTest {
      * @return {RunContext}
      */
     create<GeneratorType extends YeomanGenerator = YeomanGenerator>(GeneratorOrNamespace: string | GeneratorConstructor<GeneratorType>, settings?: RunContextSettings, envOptions?: Options): RunContext<GeneratorType>;
+    /**
+     * Prepare temporary dir without generator support.
+     * Generator and environment will be undefined.
+     */
+    prepareTemporaryDir(settings?: RunContextSettings): BasicRunContext;
 }
 declare const _default: YeomanTest;
 export default _default;

package/dist/helpers.js

@@ -7,7 +7,7 @@ import { spy as sinonSpy, stub as sinonStub } from 'sinon';
 import YeomanGenerator from 'yeoman-generator';
 import Environment from 'yeoman-environment';
 import { DummyPrompt, TestAdapter } from './adapter.js';
-import RunContext from './run-context.js';
+import RunContext, { BasicRunContext } from './run-context.js';
 import testContext from './test-context.js';
 const { cloneDeep } = _;
 /**
@@ -261,6 +261,17 @@ export class YeomanTest {
     create(GeneratorOrNamespace, settings, envOptions) {
         return this.run(GeneratorOrNamespace, settings, envOptions);
     }
+    /**
+     * Prepare temporary dir without generator support.
+     * Generator and environment will be undefined.
+     */
+    prepareTemporaryDir(settings) {
+        const context = new BasicRunContext(undefined, settings);
+        if (settings?.autoCleanup !== false) {
+            testContext.startNewContext(context);
+        }
+        return context;
+    }
 }
 export default new YeomanTest();
 export const createHelpers = options => {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { default, createHelpers, YeomanTest, type Dependency } from './helpers.js';
 export { default as RunContext, RunContextBase, type RunContextSettings } from './run-context.js';
 export { default as RunResult, type RunResultOptions } from './run-result.js';
-export { default as context } from './test-context.js';
+export { default as context, result } from './test-context.js';
 export { DummyPrompt, TestAdapter } from './adapter.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { default, createHelpers, YeomanTest } from './helpers.js';
 export { default as RunContext, RunContextBase } from './run-context.js';
 export { default as RunResult } from './run-result.js';
-export { default as context } from './test-context.js';
+export { default as context, result } from './test-context.js';
 export { DummyPrompt, TestAdapter } from './adapter.js';

package/dist/run-context.d.ts

@@ -4,7 +4,8 @@ import type Generator from 'yeoman-generator';
 import type Environment from 'yeoman-environment';
 import { type LookupOptions, type Options } from 'yeoman-environment';
 import MemFsEditor from 'mem-fs-editor';
-import RunResult from './run-result.js';
+import MemFs from 'mem-fs';
+import RunResult, { type RunResultOptions } from './run-result.js';
 import { type GeneratorConstructor, type Dependency, type YeomanTest } from './helpers.js';
 import { type DummyPromptOptions } from './adapter.js';
 /**
@@ -20,6 +21,7 @@ export type RunContextSettings = {
     oldCwd?: string;
     forwardCwd?: boolean;
     autoCleanup?: boolean;
+    memFs?: MemFs.Store;
     /**
      * File path to the generator (only used if Generator is a constructor)
      */
@@ -31,6 +33,7 @@ export type RunContextSettings = {
     namespace?: string;
 };
 type PromiseRunResult<GeneratorType extends Generator> = Promise<RunResult<GeneratorType>>;
+type MockedGeneratorFactory = (GeneratorClass?: typeof Generator) => typeof Generator;
 export declare class RunContextBase<GeneratorType extends Generator = Generator> extends EventEmitter {
     readonly mockedGenerators: Record<string, Generator>;
     env: Environment;
@@ -40,15 +43,18 @@ export declare class RunContextBase<GeneratorType extends Generator = Generator>
     completed: boolean;
     targetDirectory?: string;
     editor: MemFsEditor.Editor;
+    memFs: MemFs.Store;
+    mockedGeneratorFactory: MockedGeneratorFactory;
     protected environmentPromise?: PromiseRunResult<GeneratorType>;
     private args;
     private options;
     private answers?;
+    private keepFsState?;
     private readonly onGeneratorCallbacks;
     private readonly onTargetDirectoryCallbacks;
     private readonly onEnvironmentCallbacks;
     private readonly inDirCallbacks;
-    private readonly Generator;
+    private readonly Generator?;
     private readonly helpers;
     private readonly temporaryDir;
     private oldCwd?;
@@ -67,7 +73,7 @@ export declare class RunContextBase<GeneratorType extends Generator = Generator>
      * @param settings
      * @return {this}
      */
-    constructor(generatorType: string | GeneratorConstructor<GeneratorType> | typeof Generator, settings?: RunContextSettings, envOptions?: Options, helpers?: YeomanTest);
+    constructor(generatorType?: string | GeneratorConstructor<GeneratorType> | typeof Generator, settings?: RunContextSettings, envOptions?: Options, helpers?: YeomanTest);
     /**
      * Run the generator on the environment and promises a RunResult instance.
      * @return {PromiseRunResult} Promise a RunResult instance.
@@ -188,6 +194,7 @@ export declare class RunContextBase<GeneratorType extends Generator = Generator>
      * });
      */
     withGenerators(dependencies: Dependency[]): this;
+    withMockedGeneratorFactory(mockedGeneratorFactory: MockedGeneratorFactory): this;
     /**
      * Create mocked generators
      * @param namespaces - namespaces of mocked generators
@@ -210,6 +217,10 @@ export declare class RunContextBase<GeneratorType extends Generator = Generator>
      * @param localConfig - should look just like if called config.getAll()
      */
     withLocalConfig(localConfig: Record<string, unknown>): this;
+    /**
+     * Don't reset mem-fs state cleared to aggregate snapshots from multiple runs.
+     */
+    withKeepFsState(): this;
     /**
      * Add files to mem-fs.
      * Files will be resolved relative to targetDir.
@@ -252,6 +263,7 @@ export declare class RunContextBase<GeneratorType extends Generator = Generator>
      * @returns
      */
     onEnvironment(callback: (this: this, env: Environment) => any): this;
+    prepare(): Promise<void>;
     protected assertNotBuild(): void;
     /**
      * Build the generator and the environment.
@@ -263,6 +275,7 @@ export declare class RunContextBase<GeneratorType extends Generator = Generator>
      * @return Promise resolved on end or rejected on error
      */
     protected toPromise(): PromiseRunResult<GeneratorType>;
+    protected _createRunResultOptions(): RunResultOptions<GeneratorType>;
     /**
      * Keeps compatibility with events
      */
@@ -275,7 +288,6 @@ export declare class RunContextBase<GeneratorType extends Generator = Generator>
      * @return {this} run context instance
      */
     private setDir;
-    private _createRunResultOptions;
 }
 export default class RunContext<GeneratorType extends Generator = Generator> extends RunContextBase<GeneratorType> implements Promise<RunResult<GeneratorType>> {
     then<TResult1 = RunResult<GeneratorType>, TResult2 = never>(onfulfilled?: ((value: RunResult<GeneratorType>) => TResult1 | PromiseLike<TResult1>) | undefined | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | undefined): Promise<TResult1 | TResult2>;
@@ -283,4 +295,7 @@ export default class RunContext<GeneratorType extends Generator = Generator> ext
     finally(onfinally?: (() => void) | undefined | undefined): Promise<RunResult<GeneratorType>>;
     get [Symbol.toStringTag](): string;
 }
+export declare class BasicRunContext extends RunContext {
+    run(): PromiseRunResult<any>;
+}
 export {};

package/dist/run-context.js

@@ -7,8 +7,11 @@ import process from 'node:process';
 import _ from 'lodash';
 import tempDirectory from 'temp-dir';
 import MemFsEditor from 'mem-fs-editor';
+import MemFsEditorState from 'mem-fs-editor/lib/state.js';
+import MemFs from 'mem-fs';
 import RunResult from './run-result.js';
 import defaultHelpers from './helpers.js';
+import testContext from './test-context.js';
 const { camelCase, kebabCase, merge: lodashMerge, set: lodashSet } = _;
 export class RunContextBase extends EventEmitter {
     mockedGenerators = {};
@@ -19,10 +22,13 @@ export class RunContextBase extends EventEmitter {
     completed = false;
     targetDirectory;
     editor;
+    memFs;
+    mockedGeneratorFactory;
     environmentPromise;
     args = [];
     options = {};
     answers;
+    keepFsState;
     onGeneratorCallbacks = [];
     onTargetDirectoryCallbacks = [];
     onEnvironmentCallbacks = [];
@@ -63,6 +69,8 @@ export class RunContextBase extends EventEmitter {
             this.cd(this.settings.cwd);
         }
         this.helpers = helpers;
+        this.memFs = settings?.memFs ?? MemFs.create();
+        this.mockedGeneratorFactory = this.helpers.createMockedGenerator;
     }
     /**
      * Run the generator on the environment and promises a RunResult instance.
@@ -80,7 +88,9 @@ export class RunContextBase extends EventEmitter {
             this.helpers.restorePrompt(this.env);
             this.completed = true;
         }
-        return new RunResult(this._createRunResultOptions());
+        const runResult = new RunResult(this._createRunResultOptions());
+        testContext.runResult = runResult;
+        return runResult;
     }
     // If any event listeners is added, setup event listeners emitters
     on(eventName, listener) {
@@ -304,6 +314,10 @@ export class RunContextBase extends EventEmitter {
             }
         });
     }
+    withMockedGeneratorFactory(mockedGeneratorFactory) {
+        this.mockedGeneratorFactory = mockedGeneratorFactory;
+        return this;
+    }
     /**
      * Create mocked generators
      * @param namespaces - namespaces of mocked generators
@@ -322,7 +336,7 @@ export class RunContextBase extends EventEmitter {
      */
     withMockedGenerators(namespaces) {
         assert(Array.isArray(namespaces), 'namespaces should be an array');
-        const dependencies = namespaces.map(namespace => [this.helpers.createMockedGenerator(), namespace]);
+        const dependencies = namespaces.map(namespace => [this.mockedGeneratorFactory(), namespace]);
         const entries = dependencies.map(([generator, namespace]) => [namespace, generator]);
         Object.assign(this.mockedGenerators, Object.fromEntries(entries));
         return this.withGenerators(dependencies);
@@ -335,6 +349,13 @@ export class RunContextBase extends EventEmitter {
         assert(typeof localConfig === 'object', 'config should be an object');
         return this.onGenerator(generator => generator.config.defaults(localConfig));
     }
+    /**
+     * Don't reset mem-fs state cleared to aggregate snapshots from multiple runs.
+     */
+    withKeepFsState() {
+        this.keepFsState = true;
+        return this;
+    }
     withFiles(relativePath, files) {
         return this.onTargetDirectory(function () {
             const targetDirectory = typeof relativePath === 'string' ? pathJoin(this.targetDirectory, relativePath) : this.targetDirectory;
@@ -409,16 +430,7 @@ export class RunContextBase extends EventEmitter {
         this.onEnvironmentCallbacks.push(callback);
         return this;
     }
-    assertNotBuild() {
-        if (this.built || this.completed) {
-            throw new Error('The context is already built');
-        }
-    }
-    /**
-     * Build the generator and the environment.
-     * @return {RunContext|false} this
-     */
-    async build() {
+    async prepare() {
         this.assertNotBuild();
         this.built = true;
         if (!this.targetDirectory && this.settings.tmpdir !== false) {
@@ -437,17 +449,36 @@ export class RunContextBase extends EventEmitter {
         if (!this.targetDirectory) {
             throw new Error('targetDirectory is required');
         }
+        if (!this.keepFsState) {
+            this.memFs.each(file => {
+                // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                delete file[MemFsEditorState.STATE_CLEARED];
+            });
+        }
+        this.editor = MemFsEditor.create(this.memFs);
+        for (const onTargetDirectory of this.onTargetDirectoryCallbacks) {
+            // eslint-disable-next-line no-await-in-loop
+            await onTargetDirectory.call(this, this.targetDirectory);
+        }
+    }
+    assertNotBuild() {
+        if (this.built || this.completed) {
+            throw new Error('The context is already built');
+        }
+    }
+    /**
+     * Build the generator and the environment.
+     * @return {RunContext|false} this
+     */
+    async build() {
+        await this.prepare();
         const testEnv = await this.helpers.createTestEnv(this.envOptions.createEnv, {
             cwd: this.settings.forwardCwd ? this.targetDirectory : undefined,
+            sharedFs: this.memFs,
             ...this.options,
             ...this.envOptions,
         });
         this.env = this.envCB ? (await this.envCB(testEnv)) ?? testEnv : testEnv;
-        this.editor = MemFsEditor.create(this.env.sharedFs);
-        for (const onTargetDirectory of this.onTargetDirectoryCallbacks) {
-            // eslint-disable-next-line no-await-in-loop
-            await onTargetDirectory.call(this, this.targetDirectory);
-        }
         for (const onEnvironmentCallback of this.onEnvironmentCallbacks) {
             // eslint-disable-next-line no-await-in-loop
             await onEnvironmentCallback.call(this, this.env);
@@ -475,6 +506,21 @@ export class RunContextBase extends EventEmitter {
     async toPromise() {
         return this.environmentPromise ?? this.run();
     }
+    _createRunResultOptions() {
+        return {
+            env: this.env,
+            generator: this.generator,
+            memFs: this.env?.sharedFs ?? this.memFs,
+            settings: {
+                ...this.settings,
+            },
+            oldCwd: this.oldCwd,
+            cwd: this.targetDirectory,
+            envOptions: this.envOptions,
+            mockedGenerators: this.mockedGenerators,
+            helpers: this.helpers,
+        };
+    }
     /**
      * Keeps compatibility with events
      */
@@ -522,21 +568,6 @@ export class RunContextBase extends EventEmitter {
         this.targetDirectory = dirPath;
         return this;
     }
-    _createRunResultOptions() {
-        return {
-            env: this.env,
-            generator: this.generator,
-            memFs: this.env.sharedFs,
-            settings: {
-                ...this.settings,
-            },
-            oldCwd: this.oldCwd,
-            cwd: this.targetDirectory,
-            envOptions: this.envOptions,
-            mockedGenerators: this.mockedGenerators,
-            helpers: this.helpers,
-        };
-    }
 }
 export default class RunContext extends RunContextBase {
     // eslint-disable-next-line unicorn/no-thenable
@@ -553,3 +584,11 @@ export default class RunContext extends RunContextBase {
         return `RunContext`;
     }
 }
+export class BasicRunContext extends RunContext {
+    async run() {
+        await this.prepare();
+        const runResult = new RunResult(this._createRunResultOptions());
+        testContext.runResult = runResult;
+        return runResult;
+    }
+}

package/dist/run-result.js

@@ -45,9 +45,10 @@ export default class RunResult {
             ...this.options.settings,
             cwd: this.cwd,
             oldCwd: this.oldCwd,
+            memFs: this.memFs,
             ...settings,
             autoCleanup: false,
-        }, { ...this.options.envOptions, memFs: this.memFs, ...envOptions });
+        }, { ...this.options.envOptions, ...envOptions });
     }
     /**
      * Return an object with fs changes.

package/dist/test-context.d.ts

@@ -1,7 +1,13 @@
 import type RunContext from './run-context.js';
+import type RunResult from './run-result.js';
 declare class TestContext {
+    runResult?: RunResult;
     private runContext?;
     startNewContext(runContext: RunContext<any>): void;
 }
-declare const _default: TestContext;
-export default _default;
+declare const testContext: TestContext;
+export default testContext;
+/**
+ * Provides a proxy for last executed context result.
+ */
+export declare const result: RunResult;

package/dist/test-context.js

@@ -1,8 +1,23 @@
 class TestContext {
+    runResult;
     runContext;
     startNewContext(runContext) {
         this.runContext?.cleanupTemporaryDir();
         this.runContext = runContext;
+        this.runResult = undefined;
     }
 }
-export default new TestContext();
+const testContext = new TestContext();
+export default testContext;
+const handler2 = {
+    get(_target, prop, receiver) {
+        if (testContext.runResult === undefined) {
+            throw new Error('Last result is missing.');
+        }
+        return Reflect.get(testContext.runResult, prop, receiver);
+    },
+};
+/**
+ * Provides a proxy for last executed context result.
+ */
+export const result = new Proxy({}, handler2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yeoman-test",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Test utilities for Yeoman generators",
   "homepage": "http://yeoman.io/authoring/testing.html",
   "author": "The Yeoman Team",
@@ -51,7 +51,7 @@
     "@types/yeoman-generator": "^5.2.11",
     "inquirer": "^8.2.5",
     "lodash": "^4.17.21",
-    "mem-fs-editor": "^9.5.0",
+    "mem-fs-editor": "^9.7.0",
     "sinon": "^14.0.2",
     "temp-dir": "^3.0.0"
   },