yeoman-test 6.2.0 → 7.0.0

package/dist/run-context.js

@@ -0,0 +1,541 @@
+import crypto from 'node:crypto';
+import { existsSync, rmSync } from 'node:fs';
+import path, { resolve, isAbsolute, join as pathJoin } from 'node:path';
+import assert from 'node:assert';
+import { EventEmitter } from 'node:events';
+import process from 'node:process';
+import _ from 'lodash';
+import tempDirectory from 'temp-dir';
+import MemFsEditor from 'mem-fs-editor';
+import RunResult from './run-result.js';
+import defaultHelpers from './helpers.js';
+export class RunContextBase extends EventEmitter {
+    mockedGenerators = {};
+    env;
+    generator;
+    settings;
+    envOptions;
+    completed = false;
+    targetDirectory;
+    editor;
+    environmentPromise;
+    args = [];
+    options = {};
+    answers;
+    onGeneratorCallbacks = [];
+    onTargetDirectoryCallbacks = [];
+    onEnvironmentCallbacks = [];
+    inDirCallbacks = [];
+    Generator;
+    helpers;
+    temporaryDir = path.join(tempDirectory, crypto.randomBytes(20).toString('hex'));
+    oldCwd;
+    eventListenersSet = false;
+    envCB;
+    ran = false;
+    errored = false;
+    /**
+     * This class provide a run context object to façade the complexity involved in setting
+     * up a generator for testing
+     * @constructor
+     * @param Generator - Namespace or generator constructor. If the later
+     *                                       is provided, then namespace is assumed to be
+     *                                       'gen:test' in all cases
+     * @param settings
+     * @return {this}
+     */
+    constructor(generatorType, settings, envOptions = {}, helpers = defaultHelpers) {
+        super();
+        this.settings = {
+            namespace: 'gen:test',
+            ...settings,
+        };
+        this.Generator = generatorType;
+        if (typeof generatorType !== 'string') {
+            const { namespace, resolved } = this.settings;
+            this.withGenerators([[generatorType, namespace, resolved]]);
+        }
+        this.envOptions = envOptions;
+        this.withOptions({
+            force: true,
+            skipCache: true,
+            skipInstall: true,
+        });
+        this.oldCwd = this.settings.oldCwd;
+        if (this.settings.cwd) {
+            this.cd(this.settings.cwd);
+        }
+        this.helpers = helpers;
+    }
+    /**
+     * Run the generator on the environment and promises a RunResult instance.
+     * @return {PromiseRunResult} Promise a RunResult instance.
+     */
+    async run() {
+        if (!this.ran) {
+            await this.build();
+        }
+        try {
+            await this.env.runGenerator(this.generator);
+        }
+        finally {
+            this.helpers.restorePrompt(this.env);
+            this.completed = true;
+        }
+        return new RunResult(this._createRunResultOptions());
+    }
+    // If any event listeners is added, setup event listeners emitters
+    on(eventName, listener) {
+        super.on(eventName, listener);
+        // Don't setup emitters if on generator envent.
+        if (eventName !== 'generator') {
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            this.setupEventListeners();
+        }
+        return this;
+    }
+    /**
+     * @deprecated
+     * Clean the provided directory, then change directory into it
+     * @param  dirPath - Directory path (relative to CWD). Prefer passing an absolute
+     *                            file path for predictable results
+     * @param [cb] - callback who'll receive the folder path as argument
+     * @return run context instance
+     */
+    inDir(dirPath, cb) {
+        this.setDir(dirPath, true);
+        this.helpers.testDirectory(dirPath, () => cb?.call(this, path.resolve(dirPath)));
+        return this;
+    }
+    /**
+     * Register an callback to prepare the destination folder.
+     * @param [cb]  - callback who'll receive the folder path as argument
+     * @return this - run context instance
+     */
+    doInDir(cb) {
+        this.inDirCallbacks.push(cb);
+        return this;
+    }
+    /**
+     * @deprecated
+     * Change directory without deleting directory content.
+     * @param  dirPath - Directory path (relative to CWD). Prefer passing an absolute
+     *                            file path for predictable results
+     * @return run context instance
+     */
+    cd(dirPath) {
+        dirPath = path.resolve(dirPath);
+        this.setDir(dirPath, false);
+        try {
+            process.chdir(dirPath);
+        }
+        catch (error) {
+            this.completed = true;
+            throw new Error(`${error.message} ${dirPath}`);
+        }
+        return this;
+    }
+    /**
+     * Cleanup a temporary directory and change the CWD into it
+     *
+     * This method is called automatically when creating a RunContext. Only use it if you need
+     * to use the callback.
+     *
+     * @param [cb]  - callback who'll receive the folder path as argument
+     * @return this - run context instance
+     */
+    inTmpDir(cb) {
+        return this.inDir(this.temporaryDir, cb);
+    }
+    /**
+     * Restore cwd to initial cwd.
+     * @return {this} run context instance
+     */
+    restore() {
+        if (this.oldCwd) {
+            process.chdir(this.oldCwd);
+        }
+        return this;
+    }
+    /**
+     * Clean the directory used for tests inside inDir/inTmpDir
+     * @param  {Boolean} force - force directory cleanup for not tmpdir
+     */
+    cleanup() {
+        this.restore();
+        if (this.settings.tmpdir !== false) {
+            this.cleanTestDirectory();
+        }
+    }
+    /**
+     * Clean the directory used for tests inside inDir/inTmpDir
+     * @param  {Boolean} force - force directory cleanup for not tmpdir
+     */
+    cleanupTemporaryDir() {
+        this.restore();
+        if (this.temporaryDir && existsSync(this.temporaryDir)) {
+            rmSync(this.temporaryDir, { recursive: true });
+        }
+    }
+    /**
+     * Clean the directory used for tests inside inDir/inTmpDir
+     * @param force - force directory cleanup for not tmpdir
+     */
+    cleanTestDirectory(force = false) {
+        if (!force && this.settings.tmpdir === false) {
+            throw new Error('Cleanup test dir called with false tmpdir option.');
+        }
+        if (this.targetDirectory && existsSync(this.targetDirectory)) {
+            rmSync(this.targetDirectory, { recursive: true });
+        }
+    }
+    /**
+     * Create an environment
+     *
+     * This method is called automatically when creating a RunContext. Only use it if you need
+     * to use the callback.
+     *
+     * @param {Function} [cb] - callback who'll receive the folder path as argument
+     * @return {this} run context instance
+     */
+    withEnvironment(cb) {
+        this.envCB = cb;
+        return this;
+    }
+    /**
+     * Run lookup on the environment.
+     *
+     * @param lookups - lookup to run.
+     */
+    withLookups(lookups) {
+        return this.onEnvironment(env => {
+            lookups = Array.isArray(lookups) ? lookups : [lookups];
+            for (const lookup of lookups) {
+                env.lookup(lookup);
+            }
+        });
+    }
+    /**
+     * Provide arguments to the run context
+     * @param  args - command line arguments as Array or space separated string
+     */
+    withArguments(args) {
+        const argsArray = typeof args === 'string' ? args.split(' ') : args;
+        assert(Array.isArray(argsArray), 'args should be either a string separated by spaces or an array');
+        this.args = this.args.concat(argsArray);
+        return this;
+    }
+    /**
+     * Provide options to the run context
+     * @param  {Object} options - command line options (e.g. `--opt-one=foo`)
+     * @return {this}
+     */
+    withOptions(options) {
+        if (!options) {
+            return this;
+        }
+        // Add options as both kebab and camel case. This is to stay backward compatibles with
+        // the switch we made to meow for options parsing.
+        for (const key of Object.keys(options)) {
+            options[_.camelCase(key)] = options[key];
+            options[_.kebabCase(key)] = options[key];
+        }
+        this.options = { ...this.options, ...options };
+        return this;
+    }
+    /**
+     * @deprecated
+     * Mock the prompt with dummy answers
+     * @param  answers - Answers to the prompt questions
+     * @param  options - Options or callback.
+     * @param  {Function} [options.callback] - Callback.
+     * @param  {Boolean} [options.throwOnMissingAnswer] - Throw if a answer is missing.
+     * @return {this}
+     */
+    withPrompts(answers, options) {
+        return this.withAnswers(answers, options);
+    }
+    /**
+     * Mock answers for prompts
+     * @param  answers - Answers to the prompt questions
+     * @param  options - Options or callback.
+     * @return {this}
+     */
+    withAnswers(answers, options) {
+        const callbackSet = Boolean(this.answers);
+        this.answers = { ...this.answers, ...answers };
+        if (callbackSet)
+            return this;
+        return this.onEnvironment(env => {
+            this.helpers.mockPrompt(env, this.answers, options);
+        });
+    }
+    /**
+     * Provide dependent generators
+     * @param {Array} dependencies - paths to the generators dependencies
+     * @return {this}
+     * @example
+     * var angular = new RunContext('../../app');
+     * angular.withGenerators([
+     *   '../../common',
+     *   '../../controller',
+     *   '../../main',
+     *   [helpers.createDummyGenerator(), 'testacular:app']
+     * ]);
+     * angular.on('end', function () {
+     *   // assert something
+     * });
+     */
+    withGenerators(dependencies) {
+        assert(Array.isArray(dependencies), 'dependencies should be an array');
+        return this.onEnvironment(env => {
+            for (const dependency of dependencies) {
+                if (Array.isArray(dependency)) {
+                    env.registerStub(...dependency);
+                }
+                else {
+                    env.register(dependency);
+                }
+            }
+        });
+    }
+    /**
+     * Create mocked generators
+     * @param namespaces - namespaces of mocked generators
+     * @return this
+     * @example
+     * var angular = helpers
+     *   .create('../../app')
+     *   .withMockedGenerators([
+     *     'foo:app',
+     *     'foo:bar',
+     *   ])
+     *   .run()
+     *   .then(runResult => assert(runResult
+     *     .mockedGenerators['foo:app']
+   .calledOnce));
+     */
+    withMockedGenerators(namespaces) {
+        assert(Array.isArray(namespaces), 'namespaces should be an array');
+        const dependencies = namespaces.map(namespace => [this.helpers.createMockedGenerator(), namespace]);
+        const entries = dependencies.map(([generator, namespace]) => [namespace, generator]);
+        Object.assign(this.mockedGenerators, Object.fromEntries(entries));
+        return this.withGenerators(dependencies);
+    }
+    /**
+     * Mock the local configuration with the provided config
+     * @param localConfig - should look just like if called config.getAll()
+     */
+    withLocalConfig(localConfig) {
+        assert(typeof localConfig === 'object', 'config should be an object');
+        return this.onGenerator(generator => generator.config.defaults(localConfig));
+    }
+    withFiles(relativePath, files) {
+        return this.onTargetDirectory(function () {
+            const targetDirectory = typeof relativePath === 'string' ? pathJoin(this.targetDirectory, relativePath) : this.targetDirectory;
+            if (typeof relativePath !== 'string') {
+                files = relativePath;
+            }
+            for (const [file, content] of Object.entries(files)) {
+                const resolvedFile = isAbsolute(file) ? file : resolve(targetDirectory, file);
+                if (typeof content === 'string') {
+                    this.editor.write(resolvedFile, content);
+                }
+                else {
+                    this.editor.writeJSON(resolvedFile, content);
+                }
+            }
+        });
+    }
+    /**
+     * Add .yo-rc.json to mem-fs.
+     *
+     * @param content
+     * @returns
+     */
+    withYoRc(content) {
+        return this.withFiles({
+            '.yo-rc.json': content,
+        });
+    }
+    /**
+     * Commit mem-fs files.
+     */
+    commitFiles() {
+        return this.onTargetDirectory(async function () {
+            await this.editor.commit();
+        });
+    }
+    /**
+     * Execute callback after targetDirectory is set
+     * @param callback
+     * @returns
+     */
+    onTargetDirectory(callback) {
+        this.assertNotBuild();
+        this.onTargetDirectoryCallbacks.push(callback);
+        return this;
+    }
+    /**
+     * Execute callback after generator is ready
+     * @param callback
+     * @returns
+     */
+    onGenerator(callback) {
+        this.assertNotBuild();
+        this.onGeneratorCallbacks.push(callback);
+        return this;
+    }
+    /**
+     * Execute callback after environment is ready
+     * @param callback
+     * @returns
+     */
+    onEnvironment(callback) {
+        this.assertNotBuild();
+        this.onEnvironmentCallbacks.push(callback);
+        return this;
+    }
+    assertNotBuild() {
+        if (this.ran || this.completed) {
+            throw new Error('The context is already built');
+        }
+    }
+    /**
+     * Build the generator and the environment.
+     * @return {RunContext|false} this
+     */
+    async build() {
+        this.assertNotBuild();
+        this.ran = true;
+        if (!this.targetDirectory && this.settings.tmpdir !== false) {
+            this.inTmpDir();
+        }
+        else if (!this.targetDirectory) {
+            throw new Error('If not a temporary dir, pass the test cwd');
+        }
+        if (this.inDirCallbacks.length > 0) {
+            const targetDirectory = path.resolve(this.targetDirectory);
+            for (const cb of this.inDirCallbacks) {
+                // eslint-disable-next-line no-await-in-loop
+                await cb(targetDirectory);
+            }
+        }
+        if (!this.targetDirectory) {
+            throw new Error('targetDirectory is required');
+        }
+        const testEnv = this.helpers.createTestEnv(this.envOptions.createEnv, {
+            cwd: this.settings.forwardCwd ? this.targetDirectory : undefined,
+            ...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);
+        }
+        let { namespace } = this.settings;
+        if (typeof this.Generator === 'string') {
+            namespace = this.env.namespace(this.Generator);
+            if (namespace !== this.Generator) {
+                // Generator is a file path, it should be registered.
+                this.env.register(this.Generator);
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        this.generator = (await this.env.create(namespace, this.args, this.options));
+        for (const onGeneratorCallback of this.onGeneratorCallbacks) {
+            // eslint-disable-next-line no-await-in-loop
+            await onGeneratorCallback.call(this, this.generator);
+        }
+    }
+    /**
+     * Return a promise representing the generator run process
+     * @return Promise resolved on end or rejected on error
+     */
+    async toPromise() {
+        return this.environmentPromise ?? this.run();
+    }
+    /**
+     * Keeps compatibility with events
+     */
+    setupEventListeners() {
+        if (this.eventListenersSet) {
+            return undefined;
+        }
+        this.eventListenersSet = true;
+        this.onGenerator(generator => this.emit('ready', generator));
+        this.onGenerator(generator => this.emit('generator', generator));
+        return this.build().then(async () => this.run()
+            .catch(error => {
+            if (this.listenerCount('end') === 0 && this.listenerCount('error') === 0) {
+                // When there is no listeners throw a unhandled rejection.
+                setImmediate(async function () {
+                    // eslint-disable-next-line @typescript-eslint/no-throw-literal
+                    throw error;
+                });
+            }
+            else {
+                this.errored = true;
+                this.emit('error', error);
+            }
+        })
+            .finally(() => {
+            this.emit('end');
+        }));
+    }
+    /**
+     * Set the target directory.
+     * @private
+     * @param  {String} dirPath - Directory path (relative to CWD). Prefer passing an absolute
+     *                            file path for predictable results
+     * @return {this} run context instance
+     */
+    setDir(dirPath, tmpdir) {
+        if (this.targetDirectory) {
+            this.completed = true;
+            throw new Error('Test directory has already been set.');
+        }
+        if (tmpdir !== undefined) {
+            this.settings.tmpdir = tmpdir;
+        }
+        this.oldCwd = this.oldCwd ?? process.cwd();
+        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
+    async then(onfulfilled, onrejected) {
+        return this.toPromise().then(onfulfilled, onrejected);
+    }
+    async catch(onrejected) {
+        return this.toPromise().catch(onrejected);
+    }
+    async finally(onfinally) {
+        return this.toPromise().finally(onfinally);
+    }
+    get [Symbol.toStringTag]() {
+        return `RunContext`;
+    }
+}