yeoman-test 6.2.0 → 7.0.0

package/README.md

@@ -1,9 +1,11 @@
 # yeoman-test
+
 [![NPM version][npm-image]][npm-url]
 [![NPM Test](https://github.com/yeoman/yeoman-test/workflows/NPM%20Test/badge.svg)](https://github.com/yeoman/yeoman-test/actions?query=workflow%3A%22NPM+Test%22)
 [![Integration Build](https://github.com/yeoman/yeoman-test/workflows/Integration%20Build/badge.svg)](https://github.com/yeoman/yeoman-test/actions?query=workflow%3A%22Integration+Build%22)
 [![Dependency Status][daviddm-image]][daviddm-url]
 [![Coverage percentage][coveralls-image]][coveralls-url]
+
 > Test utilities for Yeoman generators
 
 ## Installation
@@ -78,7 +80,6 @@ describe('generator test', () => {
 
 MIT © [The Yeoman Team](http://yeoman.io)
 
-
 [npm-image]: https://badge.fury.io/js/yeoman-test.svg
 [npm-url]: https://npmjs.org/package/yeoman-test
 [travis-image]: https://travis-ci.org/yeoman/yeoman-test.svg?branch=master

package/dist/adapter.d.ts

@@ -0,0 +1,24 @@
+import inquirer from 'inquirer';
+import type Generator from 'yeoman-generator';
+import type Logger from 'yeoman-environment/lib/util/log.js';
+export type DummyPromptOptions = {
+    callback?: (answers: Generator.Answers) => Generator.Answers;
+    throwOnMissingAnswer?: boolean;
+};
+export declare class DummyPrompt {
+    answers: Generator.Answers;
+    question: inquirer.Question;
+    callback: (answers: Generator.Answers) => Generator.Answers;
+    throwOnMissingAnswer: boolean;
+    constructor(question: inquirer.Question, _rl: any, answers: Generator.Answers, mockedAnswers?: Generator.Answers, options?: ((answers: Generator.Answers) => Generator.Answers) | DummyPromptOptions);
+    run(): Promise<inquirer.Answers>;
+}
+export declare class TestAdapter {
+    promptModule: inquirer.PromptModule;
+    diff: any;
+    log: typeof Logger;
+    constructor(mockedAnswers?: any);
+    prompt(questions: any, prefilledAnswers: any): Promise<inquirer.Answers> & {
+        ui: inquirer.ui.Prompt<inquirer.Answers>;
+    };
+}

package/dist/adapter.js

@@ -0,0 +1,104 @@
+/* eslint-disable max-params */
+import events from 'node:events';
+import { PassThrough } from 'node:stream';
+import inquirer from 'inquirer';
+import { spy as sinonSpy, stub as sinonStub } from 'sinon';
+export class DummyPrompt {
+    answers;
+    question;
+    callback;
+    throwOnMissingAnswer = false;
+    constructor(question, _rl, answers, mockedAnswers, options) {
+        this.answers = { ...answers, ...mockedAnswers };
+        this.question = question;
+        if (typeof options === 'function') {
+            this.callback = options;
+        }
+        else if (options) {
+            if (options.callback) {
+                this.callback = options.callback;
+            }
+            if (options.throwOnMissingAnswer !== undefined) {
+                this.throwOnMissingAnswer = options.throwOnMissingAnswer;
+            }
+        }
+        this.callback = this.callback || (answers => answers);
+    }
+    async run() {
+        let answer = this.answers[this.question.name];
+        let isSet;
+        switch (this.question.type) {
+            case 'list': {
+                // List prompt accepts any answer value including null
+                isSet = answer !== undefined;
+                break;
+            }
+            case 'confirm': {
+                // Ensure that we don't replace `false` with default `true`
+                isSet = answer || answer === false;
+                break;
+            }
+            default: {
+                // Other prompts treat all falsy values to default
+                isSet = Boolean(answer);
+            }
+        }
+        if (!isSet) {
+            if (answer === undefined && this.question.default === undefined) {
+                const missingAnswerMessage = `yeoman-test: question ${this.question.name} was asked but answer was not provided`;
+                console.warn(missingAnswerMessage);
+                if (this.throwOnMissingAnswer) {
+                    throw new Error(missingAnswerMessage);
+                }
+            }
+            answer = this.question.default;
+            if (answer === undefined && this.question.type === 'confirm') {
+                answer = true;
+            }
+        }
+        return this.callback(answer);
+    }
+}
+export class TestAdapter {
+    promptModule;
+    diff;
+    log;
+    constructor(mockedAnswers) {
+        this.promptModule = inquirer.createPromptModule({
+            input: new PassThrough(),
+            output: new PassThrough(),
+            skipTTYChecks: true,
+        });
+        for (const promptName of Object.keys(this.promptModule.prompts)) {
+            this.promptModule.registerPrompt(promptName, class CustomDummyPrompt extends DummyPrompt {
+                constructor(question, rl, answers) {
+                    super(question, rl, answers, mockedAnswers);
+                }
+            });
+        }
+        this.diff = sinonSpy();
+        this.log = sinonSpy();
+        Object.assign(this.log, events.EventEmitter.prototype);
+        // Make sure all log methods are defined
+        const adapterMethods = [
+            'write',
+            'writeln',
+            'ok',
+            'error',
+            'skip',
+            'force',
+            'create',
+            'invoke',
+            'conflict',
+            'identical',
+            'info',
+            'table',
+        ];
+        for (const methodName of adapterMethods) {
+            this.log[methodName] = sinonStub().returns(this.log);
+        }
+    }
+    prompt(questions, prefilledAnswers) {
+        return this.promptModule(questions, prefilledAnswers);
+    }
+}

package/dist/helpers.d.ts

@@ -0,0 +1,151 @@
+import YeomanGenerator from 'yeoman-generator';
+import Environment from 'yeoman-environment';
+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';
+/**
+ * Dependencies can be path (autodiscovery) or an array [<generator>, <name>]
+ */
+export type Dependency = string | Parameters<Environment['registerStub']>;
+type GeneratorNew<GenParameter extends YeomanGenerator = YeomanGenerator> = new (...args: ConstructorParameters<typeof YeomanGenerator<GenParameter['options']>>) => YeomanGenerator<GenParameter['options']>;
+type GeneratorBuilder<GenParameter extends YeomanGenerator = YeomanGenerator> = (...args: ConstructorParameters<typeof YeomanGenerator<GenParameter['options']>>) => YeomanGenerator<GenParameter['options']>;
+export type GeneratorConstructor<GenParameter extends YeomanGenerator = YeomanGenerator> = GeneratorNew<GenParameter> | GeneratorBuilder<GenParameter>;
+/**
+ * Collection of unit test helpers. (mostly related to Mocha syntax)
+ * @class YeomanTest
+ */
+export declare class YeomanTest {
+    settings?: RunContextSettings;
+    environmentOptions?: Options;
+    generatorOptions?: GeneratorOptions;
+    /**
+     * @deprecated
+     * Create a function that will clean up the test directory,
+     * cd into it. Intended for use
+     * as a callback for the mocha `before` hook.
+     *
+     * @param dir - path to the test directory
+     * @returns mocha callback
+     */
+    setUpTestDirectory(dir: string): () => void;
+    /**
+     * @deprecated
+     * Clean-up the test directory and cd into it.
+     * Call given callback after entering the test directory.
+     * @param dir - path to the test directory
+     * @param cb - callback executed after setting working directory to dir
+     * @example
+     * testDirectory(path.join(__dirname, './temp'), function () {
+     *   fs.writeFileSync('testfile', 'Roses are red.');
+     * });
+     */
+    testDirectory(dir: string, cb?: (error?: any) => unknown): unknown;
+    /**
+     * @deprecated
+     * Answer prompt questions for the passed-in generator
+     * @param generator - a Yeoman generator or environment
+     * @param answers - an object where keys are the
+     *   generators prompt names and values are the answers to
+     *   the prompt questions
+     * @param options - Options or callback
+     * @example
+     * mockPrompt(angular, {'bootstrap': 'Y', 'compassBoostrap': 'Y'});
+     */
+    mockPrompt(envOrGenerator: YeomanGenerator | Environment, mockedAnswers?: YeomanGenerator.Answers, options?: DummyPromptOptions): void;
+    /**
+     * @deprecated
+     * Restore defaults prompts on a generator.
+     * @param generator or environment
+     */
+    restorePrompt(envOrGenerator: YeomanGenerator | Environment): void;
+    /**
+     * @deprecated
+     * Provide mocked values to the config
+     * @param generator - a Yeoman generator
+     * @param localConfig - localConfig - should look just like if called config.getAll()
+     */
+    mockLocalConfig(generator: YeomanGenerator, localConfig: any): void;
+    /**
+     * Create a mocked generator
+     */
+    createMockedGenerator(GeneratorClass?: typeof YeomanGenerator<GeneratorOptions>): SinonSpiedInstance<typeof YeomanGenerator<GeneratorOptions>>;
+    /**
+     * Create a simple, dummy generator
+     */
+    createDummyGenerator<GenParameter extends YeomanGenerator = YeomanGenerator>(Generator?: typeof YeomanGenerator): typeof YeomanGenerator<GenParameter['options']>;
+    /**
+     * Create a generator, using the given dependencies and controller arguments
+     * Dependecies can be path (autodiscovery) or an array [{generator}, {name}]
+     *
+     * @param name - the name of the generator
+     * @param dependencies - paths to the generators dependencies
+     * @param args - arguments to the generator;
+     *   if String, will be split on spaces to create an Array
+     * @param options - configuration for the generator
+     * @param localConfigOnly - passes localConfigOnly to the generators
+     * @example
+     *  var deps = ['../../app',
+     *              '../../common',
+     *              '../../controller',
+     *              '../../main',
+     *              [createDummyGenerator(), 'testacular:app']
+     *            ];
+     * var angular = createGenerator('angular:app', deps);
+     */
+    createGenerator<GeneratorType extends YeomanGenerator = YeomanGenerator>(name: string, dependencies: Dependency[], args?: string[], options?: YeomanGenerator.GeneratorOptions, localConfigOnly?: boolean): GeneratorType;
+    /**
+     * @deprecated
+     * Register a list of dependent generators into the provided env.
+     * Dependecies can be path (autodiscovery) or an array [{generator}, {name}]
+     *
+     * @param dependencies - paths to the generators dependencies
+     */
+    registerDependencies(env: Environment, dependencies: Dependency[]): void;
+    /**
+     * Shortcut to the Environment's createEnv.
+     *
+     * @param {...any} args - environment constructor arguments.
+     * @returns {Object} environment instance
+     *
+     * Use to test with specific Environment version:
+     * let createEnv;
+     * before(() => {
+     *   createEnv = stub(helper, 'createEnv').callsFake(Environment.creatEnv);
+     * });
+     * after(() => {
+     *   createEnv.restore();
+     * });
+     */
+    createEnv(...args: Parameters<typeof createEnv>): ReturnType<typeof createEnv>;
+    /**
+     * Creates a test environment.
+     *
+     * @param {Function} envContructor - environment constructor method.
+     * @param {Object} [options] - Options to be passed to the environment
+     * @returns {Object} environment instance
+     * const env = createTestEnv(require('yeoman-environment').createEnv);
+     */
+    createTestEnv(envContructor?: (args?: string | string[] | undefined, opts?: Environment.Options | undefined, adapter?: import("yeoman-environment/lib/adapter.js") | undefined) => Environment<Environment.Options>, options?: Environment.Options): Environment<Environment.Options>;
+    /**
+     * Get RunContext type
+     * @return {RunContext}
+     */
+    getRunContextType(): typeof RunContext;
+    /**
+     * Run the provided Generator
+     * @param GeneratorOrNamespace - Generator constructor or namespace
+     */
+    run<GeneratorType extends YeomanGenerator = YeomanGenerator>(GeneratorOrNamespace: string | GeneratorConstructor, settings?: RunContextSettings, envOptions?: Options): RunContext<GeneratorType>;
+    /**
+     * Prepare a run context
+     * @param  {String|Function} GeneratorOrNamespace - Generator constructor or namespace
+     * @return {RunContext}
+     */
+    create<GeneratorType extends YeomanGenerator = YeomanGenerator>(GeneratorOrNamespace: string | GeneratorConstructor, settings?: RunContextSettings, envOptions?: Options): RunContext<GeneratorType>;
+}
+declare const _default: YeomanTest;
+export default _default;
+export declare const createHelpers: (options: any) => YeomanTest;

package/dist/helpers.js

@@ -0,0 +1,258 @@
+/* eslint-disable max-params */
+import { mkdirSync, existsSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import _ from 'lodash';
+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 testContext from './test-context.js';
+/**
+ * Collection of unit test helpers. (mostly related to Mocha syntax)
+ * @class YeomanTest
+ */
+export class YeomanTest {
+    settings;
+    environmentOptions;
+    generatorOptions;
+    /**
+     * @deprecated
+     * Create a function that will clean up the test directory,
+     * cd into it. Intended for use
+     * as a callback for the mocha `before` hook.
+     *
+     * @param dir - path to the test directory
+     * @returns mocha callback
+     */
+    setUpTestDirectory(dir) {
+        return () => {
+            this.testDirectory(dir);
+        };
+    }
+    /**
+     * @deprecated
+     * Clean-up the test directory and cd into it.
+     * Call given callback after entering the test directory.
+     * @param dir - path to the test directory
+     * @param cb - callback executed after setting working directory to dir
+     * @example
+     * testDirectory(path.join(__dirname, './temp'), function () {
+     *   fs.writeFileSync('testfile', 'Roses are red.');
+     * });
+     */
+    testDirectory(dir, cb) {
+        if (!dir) {
+            throw new Error('Missing directory');
+        }
+        dir = resolve(dir);
+        // Make sure we're not deleting CWD by moving to top level folder. As we `cd` in the
+        // test dir after cleaning up, this shouldn't be perceivable.
+        process.chdir('/');
+        try {
+            if (existsSync(dir)) {
+                rmSync(dir, { recursive: true });
+            }
+            mkdirSync(dir, { recursive: true });
+            process.chdir(dir);
+            return cb?.();
+        }
+        catch (error) {
+            return cb?.(error);
+        }
+    }
+    /**
+     * @deprecated
+     * Answer prompt questions for the passed-in generator
+     * @param generator - a Yeoman generator or environment
+     * @param answers - an object where keys are the
+     *   generators prompt names and values are the answers to
+     *   the prompt questions
+     * @param options - Options or callback
+     * @example
+     * mockPrompt(angular, {'bootstrap': 'Y', 'compassBoostrap': 'Y'});
+     */
+    mockPrompt(envOrGenerator, mockedAnswers, options) {
+        const environment = 'env' in envOrGenerator ? envOrGenerator.env : envOrGenerator;
+        const { promptModule } = environment.adapter;
+        for (const name of Object.keys(promptModule.prompts)) {
+            promptModule.registerPrompt(name, class CustomDummyPrompt extends DummyPrompt {
+                constructor(question, rl, answers) {
+                    super(question, rl, answers, mockedAnswers, options);
+                }
+            });
+        }
+    }
+    /**
+     * @deprecated
+     * Restore defaults prompts on a generator.
+     * @param generator or environment
+     */
+    restorePrompt(envOrGenerator) {
+        const environment = envOrGenerator.env ?? envOrGenerator;
+        environment.adapter.promptModule.restoreDefaultPrompts();
+    }
+    /**
+     * @deprecated
+     * Provide mocked values to the config
+     * @param generator - a Yeoman generator
+     * @param localConfig - localConfig - should look just like if called config.getAll()
+     */
+    mockLocalConfig(generator, localConfig) {
+        generator.config.defaults(localConfig);
+    }
+    /**
+     * Create a mocked generator
+     */
+    createMockedGenerator(GeneratorClass = class MockedGenerator extends YeomanGenerator {
+    }) {
+        const generator = sinonSpy(GeneratorClass);
+        for (const methodName of ['run', 'queueTasks', 'runWithOptions', 'queueOwnTasks']) {
+            if (GeneratorClass.prototype[methodName]) {
+                generator.prototype[methodName] = sinonStub();
+            }
+        }
+        return generator;
+    }
+    /**
+     * Create a simple, dummy generator
+     */
+    createDummyGenerator(Generator = YeomanGenerator) {
+        class DummyGenerator extends Generator {
+            shouldRun;
+            test() {
+                this.shouldRun = true;
+            }
+        }
+        return DummyGenerator;
+    }
+    /**
+     * Create a generator, using the given dependencies and controller arguments
+     * Dependecies can be path (autodiscovery) or an array [{generator}, {name}]
+     *
+     * @param name - the name of the generator
+     * @param dependencies - paths to the generators dependencies
+     * @param args - arguments to the generator;
+     *   if String, will be split on spaces to create an Array
+     * @param options - configuration for the generator
+     * @param localConfigOnly - passes localConfigOnly to the generators
+     * @example
+     *  var deps = ['../../app',
+     *              '../../common',
+     *              '../../controller',
+     *              '../../main',
+     *              [createDummyGenerator(), 'testacular:app']
+     *            ];
+     * var angular = createGenerator('angular:app', deps);
+     */
+    createGenerator(name, dependencies, args, options, localConfigOnly = true) {
+        const env = this.createEnv([], { sharedOptions: { localConfigOnly } });
+        this.registerDependencies(env, dependencies);
+        return env.create(name, args, options);
+    }
+    /**
+     * @deprecated
+     * Register a list of dependent generators into the provided env.
+     * Dependecies can be path (autodiscovery) or an array [{generator}, {name}]
+     *
+     * @param dependencies - paths to the generators dependencies
+     */
+    registerDependencies(env, dependencies) {
+        for (const dependency of dependencies) {
+            if (Array.isArray(dependency)) {
+                env.registerStub(dependency[0], dependency[1]);
+            }
+            else {
+                env.register(dependency);
+            }
+        }
+    }
+    /**
+     * Shortcut to the Environment's createEnv.
+     *
+     * @param {...any} args - environment constructor arguments.
+     * @returns {Object} environment instance
+     *
+     * Use to test with specific Environment version:
+     * let createEnv;
+     * before(() => {
+     *   createEnv = stub(helper, 'createEnv').callsFake(Environment.creatEnv);
+     * });
+     * after(() => {
+     *   createEnv.restore();
+     * });
+     */
+    createEnv(...args) {
+        return Environment.createEnv(...args);
+    }
+    /**
+     * Creates a test environment.
+     *
+     * @param {Function} envContructor - environment constructor method.
+     * @param {Object} [options] - Options to be passed to the environment
+     * @returns {Object} environment instance
+     * const env = createTestEnv(require('yeoman-environment').createEnv);
+     */
+    createTestEnv(envContructor = this.createEnv, options = { localConfigOnly: true }) {
+        const envOptions = _.cloneDeep(this.environmentOptions ?? {});
+        if (typeof options === 'boolean') {
+            options = {
+                newErrorHandler: true,
+                ...envOptions,
+                sharedOptions: {
+                    localConfigOnly: options,
+                    ...envOptions.sharedOptions,
+                },
+            };
+        }
+        else {
+            options = {
+                newErrorHandler: true,
+                ...envOptions,
+                ...options,
+            };
+            options.sharedOptions = {
+                localConfigOnly: true,
+                ...envOptions.sharedOptions,
+                ...options.sharedOptions,
+            };
+        }
+        return envContructor([], options, new TestAdapter());
+    }
+    /**
+     * Get RunContext type
+     * @return {RunContext}
+     */
+    getRunContextType() {
+        return RunContext;
+    }
+    /**
+     * Run the provided Generator
+     * @param GeneratorOrNamespace - Generator constructor or namespace
+     */
+    run(GeneratorOrNamespace, settings, envOptions) {
+        const contextSettings = _.cloneDeep(this.settings ?? {});
+        const generatorOptions = _.cloneDeep(this.generatorOptions ?? {});
+        const RunContext = this.getRunContextType();
+        const runContext = new RunContext(GeneratorOrNamespace, { ...contextSettings, ...settings }, envOptions, this).withOptions(generatorOptions);
+        if (settings?.autoCleanup !== false) {
+            testContext.startNewContext(runContext);
+        }
+        return runContext;
+    }
+    /**
+     * Prepare a run context
+     * @param  {String|Function} GeneratorOrNamespace - Generator constructor or namespace
+     * @return {RunContext}
+     */
+    create(GeneratorOrNamespace, settings, envOptions) {
+        return this.run(GeneratorOrNamespace, settings, envOptions);
+    }
+}
+export default new YeomanTest();
+export const createHelpers = options => {
+    const helpers = new YeomanTest();
+    Object.assign(helpers, options);
+    return helpers;
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+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 { DummyPrompt, TestAdapter } from './adapter.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+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 { DummyPrompt, TestAdapter } from './adapter.js';