@api-client/core 0.3.4 → 0.3.7

package/build/src/runtime/node/ProjectRunner.d.ts

@@ -1,62 +1,87 @@
-/// <reference types="node" />
-import { EventEmitter } from 'events';
+import { HttpProject } from '../../models/HttpProject.js';
+import { ProjectFolder } from '../../models/ProjectFolder.js';
 import { Environment } from '../../models/Environment.js';
 import { Logger } from '../../lib/logging/Logger.js';
 import { IRequestLog } from '../../models/RequestLog.js';
-import { ProjectFolder } from '../../models/ProjectFolder.js';
-import { ProjectRequest } from '../../models/ProjectRequest.js';
 import { IHttpRequest } from '../../models/HttpRequest.js';
-import { HttpProject, IProjectRequestIterator } from '../../models/HttpProject.js';
-import { VariablesProcessor } from '../variables/VariablesProcessor.js';
-export interface ProjectRunnerOptions {
+import { IProjectExecutionIteration, IProjectExecutionLog } from '../reporters/Reporter.js';
+import { BaseRunner } from './BaseRunner.js';
+declare type ProjectParent = HttpProject | ProjectFolder;
+export interface IProjectRunnerOptions {
     /**
-     * When provided it overrides any project / folder defined environment.
+     * The environment to use.
+     * This can be a name or the key of the environment located under the parent or root.
+     * It can also be a path to the environment definition. If the file exists it is used. Otherwise it tried to
+     * find the environment in the project.
      */
-    environment?: Environment;
+    environment?: string;
     /**
-     * Additional variables to pass to the selected environment.
-     * This can be use to pass system variables, when needed.
-     *
-     * To use system variables tou can use `init.variables = process.env`;
+     * The parent folder to execute.
      */
-    variables?: Record<string, string>;
+    parent?: string;
     /**
-     * Overrides the default logger (console).
+     * The names or the keys of requests to execute.
+     * This can be used to limit the number of requests.
      */
-    logger?: Logger;
+    request?: string[];
     /**
-     * The event target to use.
-     * By default it creates its own target.
+     * The number of times the execution should be repeated.
+     * Default to 1.
      */
-    eventTarget?: EventTarget;
-}
-export interface ProjectRunnerRunOptions extends IProjectRequestIterator {
-}
-export interface RunResult {
+    iterations?: number;
     /**
-     * The key of the request from the HttpProject that was executed.
+     * The number of milliseconds to wait between each iteration.
+     * Default to the next frame (vary from 1 to tens of milliseconds).
      */
-    key: string;
+    iterationDelay?: number;
     /**
-     * The key of parent folder of the executed request.
+     * When set it performs parallel execution for each iteration.
+     * The number of executions at the same time depends on the number of processor cores
+     * available on the current machine. The maximum of the parallel execution
+     * is the number of available cores. When the `iterations` number is higher
+     * then the "rest" is added to the iterations per each core.
      */
-    parent?: string;
+    parallel?: boolean;
+    /**
+     * When set it includes requests in the current folder and sub-folder according to the order
+     * defined in the folder.
+     */
+    recursive?: boolean;
     /**
-     * Set when a fatal error occurred so the request couldn't be executed.
-     * This is not the same as error reported during a request. The log's response can still be IResponseError.
+     * The opposite of the `requests`. The list of names or keys of requests or folders to ignore.
+     * Note, ignore is tested before the `requests`.
      */
-    error?: boolean;
+    ignore?: string[];
     /**
-     * The error message. Always set when the `error` is `true`.
+     * The logger to use with the request factory.
+     * When not set it uses the dummy logger (no output).
      */
-    errorMessage?: string;
+    logger?: Logger;
     /**
-     * The request log.
-     * Always set when the `error` is `false`.
+     * When true it copies all system variables to the execution environment.
+     * When an array of strings, only takes system variables that are listed in the array.
+     * When a map, it uses this map as a list of variables.
+     * When not set it does not read system variables.
      */
-    log?: IRequestLog;
+    variables?: boolean | string[] | Record<string, string>;
 }
 export interface ProjectRunner {
+    /**
+     * Event dispatched when an iteration is about to start.
+     */
+    on(event: 'before-iteration', listener: (index: number, iterated: boolean) => void): this;
+    /**
+     * Event dispatched when an iteration finished.
+     */
+    on(event: 'after-iteration', listener: (index: number, iterated: boolean) => void): this;
+    /**
+     * Event dispatched before the iteration is going to sleep for the set period of time.
+     */
+    on(event: 'before-sleep', listener: () => void): this;
+    /**
+     * Event dispatched after the iteration is woke up.
+     */
+    on(event: 'after-sleep', listener: () => void): this;
     /**
      * The request object is prepared and about to be sent to the HTTP engine
      */
@@ -68,7 +93,23 @@ export interface ProjectRunner {
     /**
      * There was a general error during the request
      */
-    on(event: 'error', listener: (key: string, request: IHttpRequest, message: string) => void): this;
+    on(event: 'error', listener: (key: string, log: IRequestLog, message: string) => void): this;
+    /**
+     * Event dispatched when an iteration is about to start.
+     */
+    once(event: 'before-iteration', listener: (index: number, iterated: boolean) => void): this;
+    /**
+     * Event dispatched when an iteration finished.
+     */
+    once(event: 'after-iteration', listener: (index: number, iterated: boolean) => void): this;
+    /**
+     * Event dispatched before the iteration is going to sleep for the set period of time.
+     */
+    once(event: 'before-sleep', listener: () => void): this;
+    /**
+     * Event dispatched after the iteration is woke up.
+     */
+    once(event: 'after-sleep', listener: () => void): this;
     /**
      * The request object is prepared and about to be sent to the HTTP engine
      */
@@ -80,46 +121,107 @@ export interface ProjectRunner {
     /**
      * There was a general error during the request
      */
-    once(event: 'error', listener: (key: string, request: IHttpRequest, message: string) => void): this;
+    once(event: 'error', listener: (key: string, log: IRequestLog, message: string) => void): this;
 }
 /**
- * Runs requests in a project.
- * Developers can run the entire project with the `recursive` flag set. They can also
- * set the starting point with the `parent` options.
+ * A class to be extended to run an entire API Project for the given configuration options.
  *
- * Requests are executed in order defined in the folder.
+ * The main purpose of this class (and its children) is to iterate over requests
+ * in the project and execute them one-by-one.
+ *
+ * Implementations allow to execute the requests in a serial model or in parallel mode, where
+ * a separate workers are created to run the same HTTP requests in each worker.
+ *
+ * This class generates a run report which other programs can use to build all kinds of UIs
+ * around the data collected during the run.
  */
-export declare class ProjectRunner extends EventEmitter {
-    eventTarget: EventTarget;
-    logger?: Logger;
-    project: HttpProject;
-    protected masterEnvironment?: Environment;
-    protected extraVariables?: Record<string, string>;
+export declare abstract class ProjectRunner extends BaseRunner {
+    /**
+     * The HTTP project to run requests from.
+     */
+    project?: HttpProject;
+    /**
+     * The execution options for the project.
+     */
+    options?: IProjectRunnerOptions;
+    /**
+     * The root object (project or a folder) where the program starts iterating over the requests.
+     */
+    root?: ProjectParent;
+    /**
+     * The selected environment to apply to the requests.
+     */
+    environment?: Environment;
+    /**
+     * The events target instance for events dispatched by the request factory.
+     */
+    target: EventTarget;
+    /**
+     * This is used with `--iterations`. The index of the current iteration.
+     */
+    protected index: number;
+    /**
+     * The currently executed iteration loop.
+     */
+    protected currentIteration?: IProjectExecutionIteration;
+    /**
+     * The number of remaining iterations to run.
+     */
+    protected remaining: number;
+    /**
+     * Whether the configuration allows iterations (the parallel mode).
+     */
+    protected hasIterations: boolean;
+    /**
+     * When set it won't amit any event.
+     * This can be used in a background worker when events are never handled.
+     */
+    noEmit: boolean;
+    constructor();
+    /**
+     * A required step before running the project.
+     * It configures the execution context. It may throw an error when configuration is not valid.
+     */
+    configure(project: HttpProject, opts?: IProjectRunnerOptions): Promise<void>;
+    /**
+     * Executes the requests in the project.
+     * @returns The execution log created by calling the `createReport()` function.
+     */
+    abstract execute(): Promise<IProjectExecutionLog>;
+    /**
+     * Creates the report of the execution.
+     */
+    protected createReport(): Promise<IProjectExecutionLog>;
+    /**
+     * Reads the environment data to use with the execution.
+     * If the configured environment is a location of a file
+     * it is read as API Client's environment and used in the execution.
+     * Otherwise it searches for the environment in the list of the defined
+     * environments by the name of the key.
+     *
+     * It throws when the environment cannot be found or when the file contents is invalid.
+     */
+    protected getEnvironment(): Promise<Environment | undefined>;
     /**
-     * The variables processor instance.
+     * Runs the requests from the project as configured.
      */
-    protected variablesProcessor: VariablesProcessor;
-    constructor(project: HttpProject, opts?: ProjectRunnerOptions);
+    protected executeIteration(): Promise<void>;
     /**
-     * Runs the request from the project root or a specified folder.
-     * @param options Run options.
-     * @returns A promise with the run result.
+     * Retargets the "request" event from the factory.
      */
-    run(options?: ProjectRunnerRunOptions): Promise<RunResult[]>;
-    protected execute(request: ProjectRequest, variables: Record<string, string>): Promise<RunResult>;
-    protected getVariables(parent: HttpProject | ProjectFolder): Promise<Record<string, string>>;
-    protected createEnvironment(parent: HttpProject | ProjectFolder): Promise<Record<string, string>>;
+    protected _requestHandler(key: string, request: IHttpRequest): void;
     /**
-     * Reads the list of the environments to apply to this runtime.
+     * Retargets the "response" event from the factory.
      */
-    protected readEnvironments(parent: HttpProject | ProjectFolder): Promise<Environment[]>;
+    protected _responseHandler(key: string, log: IRequestLog): void;
     /**
-     * Reads the variables and the base URI from the passed environments.
+     * Retargets the "error" event from the factory.
      */
-    protected applyVariables(environments: Environment[]): Promise<Record<string, string>>;
+    protected _errorHandler(key: string, log: IRequestLog, message: string): void;
     /**
-     * When defined it applies the serve's base URI to relative URLs.
-     * @param currentUrl The URL to process.
+     * @returns Reads the system variables based on the library configuration.
      */
-    protected prepareRequestUrl(currentUrl: string, variables: Record<string, string>): string;
+    protected getSystemVariables(): Record<string, string>;
+    private _readSystemVariables;
 }
+export {};

package/build/src/runtime/node/ProjectRunner.js

@@ -1,178 +1,230 @@
-import { EventEmitter } from 'events';
-import { Kind as ProjectFolderKind } from '../../models/ProjectFolder.js';
-import { VariablesStore } from './VariablesStore.js';
-import { VariablesProcessor } from '../variables/VariablesProcessor.js';
-import { RequestFactory } from './RequestFactory.js';
-import { EventTypes } from '../../events/EventTypes.js';
+import { SerializableError } from '../../models/SerializableError.js';
+import { Environment } from '../../models/Environment.js';
+import { DummyLogger } from '../../lib/logging/DummyLogger.js';
+import { ProjectRequestRunner } from './ProjectRequestRunner.js';
+import { pathExists, readJson } from '../../lib/fs/Fs.js';
+import { BaseRunner } from './BaseRunner.js';
 /**
- * Runs requests in a project.
- * Developers can run the entire project with the `recursive` flag set. They can also
- * set the starting point with the `parent` options.
+ * A class to be extended to run an entire API Project for the given configuration options.
  *
- * Requests are executed in order defined in the folder.
+ * The main purpose of this class (and its children) is to iterate over requests
+ * in the project and execute them one-by-one.
+ *
+ * Implementations allow to execute the requests in a serial model or in parallel mode, where
+ * a separate workers are created to run the same HTTP requests in each worker.
+ *
+ * This class generates a run report which other programs can use to build all kinds of UIs
+ * around the data collected during the run.
  */
-export class ProjectRunner extends EventEmitter {
-    eventTarget;
-    logger;
+export class ProjectRunner extends BaseRunner {
+    /**
+     * The HTTP project to run requests from.
+     */
     project;
-    masterEnvironment;
-    extraVariables;
     /**
-     * The variables processor instance.
+     * The execution options for the project.
+     */
+    options;
+    /**
+     * The root object (project or a folder) where the program starts iterating over the requests.
+     */
+    root;
+    /**
+     * The selected environment to apply to the requests.
+     */
+    environment;
+    /**
+     * The events target instance for events dispatched by the request factory.
+     */
+    target = new EventTarget();
+    /**
+     * This is used with `--iterations`. The index of the current iteration.
+     */
+    index = 0;
+    /**
+     * The currently executed iteration loop.
      */
-    variablesProcessor = new VariablesProcessor();
-    constructor(project, opts = {}) {
+    currentIteration;
+    /**
+     * The number of remaining iterations to run.
+     */
+    remaining = 1;
+    /**
+     * Whether the configuration allows iterations (the parallel mode).
+     */
+    hasIterations = false;
+    /**
+     * When set it won't amit any event.
+     * This can be used in a background worker when events are never handled.
+     */
+    noEmit = false;
+    constructor() {
         super();
-        this.project = project;
-        this.logger = opts.logger;
-        this.eventTarget = opts.eventTarget || new EventTarget();
-        this.masterEnvironment = opts.environment;
-        this.extraVariables = opts.variables;
+        this._requestHandler = this._requestHandler.bind(this);
+        this._responseHandler = this._responseHandler.bind(this);
+        this._errorHandler = this._errorHandler.bind(this);
     }
     /**
-     * Runs the request from the project root or a specified folder.
-     * @param options Run options.
-     * @returns A promise with the run result.
-     */
-    async run(options) {
-        const { project } = this;
-        const executed = [];
-        for (const request of project.requestIterator(options)) {
-            const parent = request.getParent() || project;
-            let variables;
-            if (VariablesStore.has(parent)) {
-                variables = VariablesStore.get(parent);
-            }
-            else {
-                variables = await this.getVariables(parent);
-                VariablesStore.set(parent, variables);
-            }
-            const info = await this.execute(request, variables);
-            executed.push(info);
+     * A required step before running the project.
+     * It configures the execution context. It may throw an error when configuration is not valid.
+     */
+    async configure(project, opts = {}) {
+        this.project = project;
+        this.options = opts || {};
+        if (typeof this.options.iterations === 'number' && this.options.iterations >= 0) {
+            this.remaining = this.options.iterations;
         }
-        return executed;
+        this.hasIterations = this.remaining > 1;
+        const root = opts.parent ? project.findFolder(opts.parent) : project;
+        if (!root) {
+            throw new Error(`Unable to locate the folder: ${opts.parent}`);
+        }
+        this.root = root;
+        this.environment = await this.getEnvironment();
+    }
+    /**
+     * Creates the report of the execution.
+     */
+    async createReport() {
+        const log = {
+            started: this.startTime,
+            ended: this.endTime,
+            iterations: this.executed,
+        };
+        return log;
     }
-    async execute(request, variables) {
-        const config = request.getConfig();
-        const factory = new RequestFactory(this.eventTarget);
-        factory.variables = variables;
-        if (request.authorization) {
-            factory.authorization = request.authorization.map(i => i.toJSON());
+    /**
+     * Reads the environment data to use with the execution.
+     * If the configured environment is a location of a file
+     * it is read as API Client's environment and used in the execution.
+     * Otherwise it searches for the environment in the list of the defined
+     * environments by the name of the key.
+     *
+     * It throws when the environment cannot be found or when the file contents is invalid.
+     */
+    async getEnvironment() {
+        const { options } = this;
+        if (!options) {
+            throw new Error(`Run configure() first.`);
         }
-        if (request.actions) {
-            factory.actions = request.actions.toJSON();
+        if (!options.environment) {
+            return;
         }
-        if (request.clientCertificate) {
-            factory.certificates = [request.clientCertificate];
+        const fileExists = await pathExists(options.environment);
+        if (fileExists) {
+            const contents = await readJson(options.environment);
+            return new Environment(contents);
         }
-        if (config.enabled !== false) {
-            factory.config = config.toJSON();
+        const root = this.root;
+        const envs = root.getEnvironments();
+        const env = envs.find(i => i.key === options.environment || i.info.name === options.environment);
+        if (!env) {
+            throw new SerializableError(`The environment cannot be found: ${options.environment}.`, 'EENVNOTFOUND');
+        }
+        return env;
+    }
+    /**
+     * Runs the requests from the project as configured.
+     */
+    async executeIteration() {
+        const { environment, project, options, hasIterations, index, noEmit } = this;
+        if (!options || !project) {
+            throw new Error(`Run configure() first.`);
         }
-        if (this.logger) {
-            factory.logger = this.logger;
+        if (!noEmit) {
+            this.emit('before-iteration', index, hasIterations);
         }
-        const info = {
-            key: request.key,
+        const runner = new ProjectRequestRunner(project, {
+            environment,
+            logger: options.logger ? options.logger : new DummyLogger(),
+            eventTarget: this.target,
+            variables: this.getSystemVariables(),
+        });
+        runner.on('request', this._requestHandler);
+        runner.on('response', this._responseHandler);
+        runner.on('error', this._errorHandler);
+        this.currentIteration = {
+            index: this.index,
+            executed: [],
         };
-        const requestData = request.expects.toJSON();
-        requestData.url = this.prepareRequestUrl(requestData.url, variables);
-        function variableHandler(e) {
-            if (e.defaultPrevented) {
-                return;
-            }
-            const { name, value } = e.detail;
-            variables[name] = value;
-            e.preventDefault();
-            e.detail.result = Promise.resolve();
-        }
-        this.eventTarget.addEventListener(EventTypes.Environment.set, variableHandler);
         try {
-            // Below replaces the single call to the `run()` function of the factory to 
-            // report via the events a request object that has evaluated with the Jexl library.
-            const requestCopy = await factory.processRequestVariables(requestData);
-            this.emit('request', request.key, { ...requestCopy });
-            await factory.processRequestLogic(requestCopy);
-            const result = await factory.executeRequest(requestCopy);
-            await factory.processResponse(result);
-            request.setLog(result);
-            info.log = result;
-            this.emit('response', request.key, { ...result });
+            await runner.run({
+                parent: options.parent,
+                requests: options.request,
+                ignore: options.ignore,
+                recursive: options.recursive
+            });
         }
         catch (e) {
-            info.error = true;
-            info.errorMessage = e.message;
-            this.emit('error', request.key, { ...requestData }, info.errorMessage);
+            const cause = e;
+            console.error(e);
+            this.currentIteration.error = cause.message || 'Unknown error ocurred';
+            // ...
         }
-        this.eventTarget.removeEventListener(EventTypes.Environment.set, variableHandler);
-        return info;
-    }
-    async getVariables(parent) {
-        if (this.masterEnvironment) {
-            return this.applyVariables([this.masterEnvironment]);
+        this.executed.push(this.currentIteration);
+        if (!noEmit) {
+            this.emit('after-iteration', index, hasIterations);
         }
-        return this.createEnvironment(parent);
     }
-    async createEnvironment(parent) {
-        const envs = await this.readEnvironments(parent);
-        return this.applyVariables(envs);
+    /**
+     * Retargets the "request" event from the factory.
+     */
+    _requestHandler(key, request) {
+        if (!this.noEmit) {
+            this.emit('request', key, request);
+        }
     }
     /**
-     * Reads the list of the environments to apply to this runtime.
+     * Retargets the "response" event from the factory.
      */
-    async readEnvironments(parent) {
-        const folderKey = parent.kind === ProjectFolderKind ? parent.key : undefined;
-        return this.project.readEnvironments({ folderKey });
+    _responseHandler(key, log) {
+        this.currentIteration?.executed.push(log);
+        if (!this.noEmit) {
+            this.emit('response', key, log);
+        }
     }
     /**
-     * Reads the variables and the base URI from the passed environments.
+     * Retargets the "error" event from the factory.
      */
-    async applyVariables(environments) {
-        let baseUri = '';
-        const variables = [];
-        environments.forEach((environment) => {
-            const { server, variables: envVariables } = environment;
-            if (server) {
-                baseUri = server.readUri();
-            }
-            if (envVariables.length) {
-                envVariables.forEach((item) => {
-                    const defined = variables.findIndex(i => i.name === item.name);
-                    if (defined >= 0) {
-                        variables[defined] = item;
-                    }
-                    else {
-                        variables.push(item);
-                    }
-                });
-            }
-        });
-        const { extraVariables } = this;
-        const ctx = VariablesProcessor.createContextFromProperties(variables);
-        if (extraVariables) {
-            Object.keys(extraVariables).forEach((key) => {
-                ctx[key] = extraVariables[key];
-            });
+    _errorHandler(key, log, message) {
+        this.currentIteration?.executed.push(log);
+        if (!this.noEmit) {
+            this.emit('error', key, log, message);
         }
-        // the `baseUri` is reserved and always set to the environment's `baseUri`.
-        ctx.baseUri = baseUri || '';
-        return this.variablesProcessor.buildContext(ctx);
     }
     /**
-     * When defined it applies the serve's base URI to relative URLs.
-     * @param currentUrl The URL to process.
+     * @returns Reads the system variables based on the library configuration.
      */
-    prepareRequestUrl(currentUrl, variables) {
-        const { baseUri } = variables;
-        if (!baseUri) {
-            return currentUrl;
+    getSystemVariables() {
+        const result = {};
+        const { options } = this;
+        if (!options) {
+            return result;
+        }
+        const { variables } = options;
+        if (typeof variables === 'undefined') {
+            return result;
         }
-        if (currentUrl.startsWith('http:') || currentUrl.startsWith('https:')) {
-            return currentUrl;
+        if (typeof variables === 'boolean') {
+            return variables ? this._readSystemVariables() : result;
         }
-        if (currentUrl.startsWith('/')) {
-            return `${baseUri}${currentUrl}`;
+        if (Array.isArray(variables)) {
+            return this._readSystemVariables(variables);
         }
-        return `${baseUri}/${currentUrl}`;
+        return variables;
+    }
+    _readSystemVariables(names) {
+        const result = {};
+        Object.keys(process.env).forEach((key) => {
+            if (names && !names.includes(key)) {
+                return;
+            }
+            const value = process.env[key];
+            if (value) {
+                result[key] = value;
+            }
+        });
+        return result;
     }
 }
 //# sourceMappingURL=ProjectRunner.js.map