yeoman-test 6.2.0 → 7.0.0

package/dist/run-context.d.ts

@@ -0,0 +1,279 @@
+/// <reference types="node" resolution-mode="require"/>
+import { EventEmitter } from 'node:events';
+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 { type GeneratorConstructor, type Dependency, type YeomanTest } from './helpers.js';
+import { type DummyPromptOptions } from './adapter.js';
+/**
+ * Provides settings for creating a `RunContext`.
+ */
+export type RunContextSettings = {
+    /**
+     * Automatically run this generator in a tmp dir
+     * @default true
+     */
+    tmpdir?: boolean;
+    cwd?: string;
+    oldCwd?: string;
+    forwardCwd?: boolean;
+    autoCleanup?: boolean;
+    /**
+     * File path to the generator (only used if Generator is a constructor)
+     */
+    resolved?: string;
+    /**
+     * Namespace (only used if Generator is a constructor)
+     * @default 'gen:test'
+     */
+    namespace?: string;
+};
+type PromiseRunResult<GeneratorType extends Generator> = Promise<RunResult<GeneratorType>>;
+export declare class RunContextBase<GeneratorType extends Generator> extends EventEmitter {
+    readonly mockedGenerators: Record<string, Generator>;
+    env: Environment;
+    generator: GeneratorType;
+    readonly settings: RunContextSettings;
+    readonly envOptions: Environment.Options;
+    completed: boolean;
+    targetDirectory?: string;
+    editor: MemFsEditor.Editor;
+    protected environmentPromise?: PromiseRunResult<GeneratorType>;
+    private args;
+    private options;
+    private answers?;
+    private readonly onGeneratorCallbacks;
+    private readonly onTargetDirectoryCallbacks;
+    private readonly onEnvironmentCallbacks;
+    private readonly inDirCallbacks;
+    private readonly Generator;
+    private readonly helpers;
+    private readonly temporaryDir;
+    private oldCwd?;
+    private eventListenersSet;
+    private envCB;
+    private ran;
+    private errored;
+    /**
+     * 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: string | GeneratorConstructor | 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.
+     */
+    run(): PromiseRunResult<GeneratorType>;
+    on(eventName: string | symbol, listener: (...args: any[]) => void): 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: string, cb?: (folderPath: string) => void): 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: (folderPath: string) => void): 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: string): 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?: (folderPath: string) => void): this;
+    /**
+     * Restore cwd to initial cwd.
+     * @return {this} run context instance
+     */
+    restore(): this;
+    /**
+     * Clean the directory used for tests inside inDir/inTmpDir
+     * @param  {Boolean} force - force directory cleanup for not tmpdir
+     */
+    cleanup(): void;
+    /**
+     * Clean the directory used for tests inside inDir/inTmpDir
+     * @param  {Boolean} force - force directory cleanup for not tmpdir
+     */
+    cleanupTemporaryDir(): void;
+    /**
+     * Clean the directory used for tests inside inDir/inTmpDir
+     * @param force - force directory cleanup for not tmpdir
+     */
+    cleanTestDirectory(force?: boolean): void;
+    /**
+     * 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: any): this;
+    /**
+     * Run lookup on the environment.
+     *
+     * @param lookups - lookup to run.
+     */
+    withLookups(lookups: LookupOptions | LookupOptions[]): this;
+    /**
+     * Provide arguments to the run context
+     * @param  args - command line arguments as Array or space separated string
+     */
+    withArguments(args: string | string[]): this;
+    /**
+     * Provide options to the run context
+     * @param  {Object} options - command line options (e.g. `--opt-one=foo`)
+     * @return {this}
+     */
+    withOptions(options: any): 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: Generator.Answers, options?: DummyPromptOptions): this;
+    /**
+     * Mock answers for prompts
+     * @param  answers - Answers to the prompt questions
+     * @param  options - Options or callback.
+     * @return {this}
+     */
+    withAnswers(answers: Generator.Answers, options?: DummyPromptOptions): this;
+    /**
+     * 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: Dependency[]): this;
+    /**
+     * 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: string[]): this;
+    /**
+     * Mock the local configuration with the provided config
+     * @param localConfig - should look just like if called config.getAll()
+     */
+    withLocalConfig(localConfig: Record<string, unknown>): this;
+    /**
+     * Add files to mem-fs.
+     * Files will be resolved relative to targetDir.
+     * @param files
+     */
+    withFiles(files: Record<string, string | Record<string, unknown>>): this;
+    withFiles(relativePath: string, files: Record<string, string | Record<string, unknown>>): this;
+    /**
+     * Add .yo-rc.json to mem-fs.
+     *
+     * @param content
+     * @returns
+     */
+    withYoRc(content: string | Record<string, unknown>): this;
+    /**
+     * Commit mem-fs files.
+     */
+    commitFiles(): this;
+    /**
+     * Execute callback after targetDirectory is set
+     * @param callback
+     * @returns
+     */
+    onTargetDirectory(callback: (this: this, targetDirectory: string) => any): this;
+    /**
+     * Execute callback after generator is ready
+     * @param callback
+     * @returns
+     */
+    onGenerator(callback: (this: this, generator: GeneratorType) => any): this;
+    /**
+     * Execute callback after environment is ready
+     * @param callback
+     * @returns
+     */
+    onEnvironment(callback: (this: this, env: Environment) => any): this;
+    protected assertNotBuild(): void;
+    /**
+     * Build the generator and the environment.
+     * @return {RunContext|false} this
+     */
+    protected build(): Promise<void>;
+    /**
+     * Return a promise representing the generator run process
+     * @return Promise resolved on end or rejected on error
+     */
+    protected toPromise(): PromiseRunResult<GeneratorType>;
+    /**
+     * Keeps compatibility with events
+     */
+    private setupEventListeners;
+    /**
+     * 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
+     */
+    private setDir;
+    private _createRunResultOptions;
+}
+export default class RunContext<GeneratorType extends 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>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | undefined): Promise<RunResult<GeneratorType> | TResult>;
+    finally(onfinally?: (() => void) | undefined | undefined): Promise<RunResult<GeneratorType>>;
+    get [Symbol.toStringTag](): string;
+}
+export {};