act-test-runner 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 original authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# act-test-runner
+
+[![Build](https://github.com/pshevche/act-test-runner/actions/workflows/verify.yaml/badge.svg)](https://github.com/pshevche/act-test-runner/actions/workflows/verify.yaml)
+
+**Convenient wrapper around [act](https://github.com/nektos/act) for implementing e2e tests for GitHub actions**
+
+The library defines an opinionated runner interface for executing GitHub workflows locally using
+the [act](https://github.com/nektos/act) runner.
+
+Consumers can assert on the outcome of the workflow execution, such as the jobs run, workflow's output, or artifacts
+persisted in the artifact server or action cache.
+
+## Sneak preview
+
+```JavaScript
+test('custom workflow with event', async () => {
+  const result = await new ActRunner()
+    .withWorkflow({
+      body: `
+name: Workflow printing the PR title
+on:
+  pull_request:
+    types: [opened]
+
+jobs:
+  print_pr_title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Print PR title
+        if: github.event_name == 'pull_request'
+        run: |
+          echo "PR Title: ${{ github.event.pull_request.title }}"
+  `,
+    })
+    .withEvent('pull_request', {
+      pull_request: {
+        title: 'Example PR payload as object',
+      },
+    })
+    .run();
+
+  expect(result.status).toBe(ActExecStatus.SUCCESS);
+  const job = result.jobs['print_pr_title']!;
+  expect(job.status).toBe(ActExecStatus.SUCCESS);
+  expect(job.output).toContain('PR Title: Example PR payload as object');
+});
+```
+
+## Useful links
+
+- [Wiki](https://github.com/pshevche/act-test-runner/wiki): full documentation, including a walkthrough of the public API and more usage examples.
+- [Known limitations](https://github.com/pshevche/act-test-runner/wiki/Known-limitations): constraints to be aware of before adopting the library.
+- [Examples](https://github.com/pshevche/act-test-runner/wiki/Examples): representative test cases showing the API in action, including testing a local action under development.
+- [nektos/act](https://github.com/nektos/act): GitHub actions runner used by the plugin.
+- [act User Guide](https://nektosact.com): describes various configuration options that the runner provides, as well as
+  the format for input files.

package/dist/ActExecStatus.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2025 original authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+/**
+ * Outcome of the workflow or job execution.
+ */
+export declare enum ActExecStatus {
+    SUCCESS = 0,
+    FAILED = 1,
+    SKIPPED = 2
+}

package/dist/ActExecStatus.js

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2025 original authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+/**
+ * Outcome of the workflow or job execution.
+ */
+export var ActExecStatus;
+(function (ActExecStatus) {
+    ActExecStatus[ActExecStatus["SUCCESS"] = 0] = "SUCCESS";
+    ActExecStatus[ActExecStatus["FAILED"] = 1] = "FAILED";
+    ActExecStatus[ActExecStatus["SKIPPED"] = 2] = "SKIPPED";
+})(ActExecStatus || (ActExecStatus = {}));

package/dist/ActJobExecResult.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2025 original authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+import { ActExecStatus } from './ActExecStatus.js';
+/**
+ * Job execution result for inspection.
+ */
+export declare class ActJobExecResult {
+    /**
+     * Name of the job run.
+     */
+    readonly name: string;
+    /**
+     * Result of the job execution.
+     */
+    readonly status: ActExecStatus;
+    /**
+     * Job's console output.
+     */
+    readonly output: string;
+    constructor(name: string, status: ActExecStatus, output: string);
+}

package/dist/ActJobExecResult.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2025 original authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+/**
+ * Job execution result for inspection.
+ */
+export class ActJobExecResult {
+    /**
+     * Name of the job run.
+     */
+    name;
+    /**
+     * Result of the job execution.
+     */
+    status;
+    /**
+     * Job's console output.
+     */
+    output;
+    constructor(name, status, output) {
+        this.name = name;
+        this.status = status;
+        this.output = output;
+    }
+}

package/dist/ActOutputListener.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) 2026 original authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/** Identifier of the owner of this message: job or step. */
+export type ActJobOrStepDescriptor = {
+    id: string;
+    name: string;
+};
+/** Message's log level. */
+export declare const ActOutputLevel: {
+    readonly DEBUG: 'debug';
+    readonly INFO: 'info';
+    readonly WARNING: 'warning';
+    readonly ERROR: 'error';
+};
+/** Message's log level. */
+export type ActOutputLevel = (typeof ActOutputLevel)[keyof typeof ActOutputLevel];
+/** Single message in the act output stream. */
+export type ActOutput = {
+    job?: ActJobOrStepDescriptor;
+    step?: ActJobOrStepDescriptor;
+    message: string;
+    level: ActOutputLevel;
+    time: Date;
+};
+/** Listen to the act output stream. */
+export interface ActOutputListener {
+    /** @param output Act output represented as a structured object. */
+    onOutput(output: ActOutput): void;
+}
+/** Act output listener that forwards the output to the console. */
+export declare class StdStreamOutputListener implements ActOutputListener {
+    onOutput(output: ActOutput): void;
+}
+/** Composite act output listener that delegates to all provided listeners. */
+export declare class CompositeActOutputListener implements ActOutputListener {
+    private readonly listeners;
+    constructor(listeners: ActOutputListener[]);
+    onOutput(output: ActOutput): void;
+}

package/dist/ActOutputListener.js

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 original authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { formattedMessage } from './internal/ActJsonOutput.js';
+/** Message's log level. */
+export const ActOutputLevel = {
+    DEBUG: 'debug',
+    INFO: 'info',
+    WARNING: 'warning',
+    ERROR: 'error',
+};
+/** Act output listener that forwards the output to the console. */
+export class StdStreamOutputListener {
+    onOutput(output) {
+        console.log(formattedMessage(output.message, output.job?.name));
+    }
+}
+/** Composite act output listener that delegates to all provided listeners. */
+export class CompositeActOutputListener {
+    listeners;
+    constructor(listeners) {
+        this.listeners = listeners;
+    }
+    onOutput(output) {
+        this.listeners.forEach((it) => it.onOutput(output));
+    }
+}

package/dist/ActResourceSpec.d.ts

@@ -0,0 +1,6 @@
+export declare class ActResourceSpec {
+    readonly path: string;
+    readonly host: string | undefined;
+    readonly port: number | undefined;
+    constructor(path: string, host: string | undefined, port: number | undefined);
+}

package/dist/ActRunner.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) 2026 original authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { WebhookEventMap, WebhookEventName } from '@octokit/webhooks-types';
+import type { ActValueSource, ActWorkflowSource, ActResourceServerSpec, ActProcessOptions } from './ActRunnerOptions.js';
+import type { ActMatrixValues, ActWorkflowExecResult } from './ActRunnerResult.js';
+import { ActOutputListener } from './ActOutputListener.js';
+import { PartialDeep } from './utils/types.js';
+type EventPayload<TEventType extends WebhookEventName | undefined = undefined> = (TEventType extends WebhookEventName ? PartialDeep<WebhookEventMap[TEventType]> | string : string) | undefined;
+/**
+ * Invokes `act`, allowing end-to-end testing of custom GitHub actions and
+ * workflows.
+ *
+ * Typically, the test code will provide a workflow file or workflow body to
+ * run, as well as required workflow inputs, such as environment variables or
+ * secrets.
+ *
+ * Assertions can then be made on the outcome of the `run()` method invocation,
+ * such as the jobs run, workflow output, or artifacts persisted in the artifact
+ * server or action cache.
+ *
+ * The runner cannot be used concurrently due to limitations on the `act` side.
+ *
+ * Each instance is single-use: calling `run()` more than once on the same
+ * instance rejects with an `ActRunnerError`. Create a new instance for each
+ * run.
+ */
+export declare class ActRunner<TEventType extends WebhookEventName | undefined = undefined, TEventPayload extends EventPayload<TEventType> = undefined> {
+    private actExecutable;
+    private workingDir;
+    private workflowSource;
+    private eventType;
+    private eventPayloadFileOrBody;
+    private envSource;
+    private inputsSource;
+    private secretsSource;
+    private variablesSource;
+    private matrixValues;
+    private cacheServer;
+    private artifactServer;
+    private additionalArgs;
+    private outputListener;
+    private hasRun;
+    /**
+     * Sets the path to the `act` executable (default: `act` binary on the
+     * `PATH`). Useful in the CI environments, where the executable is provisioned
+     * on demand in a controlled location.
+     *
+     * @param actExecutable - Path to the `act` executable.
+     */
+    withActExecutable(actExecutable: string): this;
+    /**
+     * Sets the directory to use for the runner's storage needs (default:
+     * directory in user's temp folder).
+     *
+     * @param {string} workingDir - The runner's working directory
+     */
+    withWorkingDir(workingDir: string): this;
+    /**
+     * Specifies the GitHub workflow to run, either as a file path or an inline
+     * body.
+     *
+     * @param source - The workflow source
+     */
+    withWorkflow(source: ActWorkflowSource): this;
+    /**
+     * Configures the event that triggers the workflow run (e.g., `push`). If
+     * unspecified, the first event type specified in the workflow definition will
+     * be used.
+     *
+     * @param type - Type of the event to trigger the workflow
+     * @param payloadFileOrBody - Event payload as plain JS object or path to the
+     *   JSON file
+     */
+    withEvent<E extends WebhookEventName, EP extends EventPayload<E>>(type: E, payloadFileOrBody?: EP): ActRunner<E, EP>;
+    /**
+     * Specifies environment variables to use when invoking the given workflow,
+     * provided via a file, inline values, or both. Replaces any environment
+     * variables set by a previous call to this method.
+     *
+     * @param source - Environment variables source
+     */
+    withEnv(source: ActValueSource): this;
+    /**
+     * Specifies inputs values to use when invoking the given workflow, provided
+     * via a file, inline values, or both. Replaces any inputs values set by a
+     * previous call to this method.
+     *
+     * @param source - Inputs values source
+     */
+    withInputs(source: ActValueSource): this;
+    /**
+     * Specifies secrets values to use when invoking the given workflow, provided
+     * via a file, inline values, or both. Replaces any secrets values set by a
+     * previous call to this method.
+     *
+     * @param source - Secrets values source
+     */
+    withSecrets(source: ActValueSource): this;
+    /**
+     * Specifies workflow variables values to use when invoking the given
+     * workflow, provided via a file, inline values, or both. Replaces any
+     * variables values set by a previous call to this method.
+     *
+     * @param source - Variables values source
+     */
+    withVariables(source: ActValueSource): this;
+    /**
+     * Set matrix values to run the workflow with. If undefined, all combinations
+     * specified in the workflow definition will be invoked. Replaces any matrix
+     * values set by a previous call to this method.
+     *
+     * @param matrixValues - Matrix values to run the workflow with
+     */
+    withMatrix(matrixValues: ActMatrixValues): this;
+    /**
+     * Configures the cache server to be used by the given workflow.
+     *
+     * @param spec - Cache server configuration
+     */
+    withCacheServer(spec: ActResourceServerSpec): this;
+    /**
+     * Configures the artifact server to be used by the given workflow.
+     *
+     * @param spec - Artifact server configuration
+     */
+    withArtifactServer(spec: ActResourceServerSpec): this;
+    /**
+     * Arbitrary additional arguments to pass to the `act` execution.
+     *
+     * @param {...string} args - Additional arguments to invoke `act` with
+     */
+    withAdditionalArgs(...args: string[]): this;
+    /**
+     * Forwards the act output to the supplied listeners. When no listener is
+     * specified, forwards the output to the console.
+     *
+     * @param listeners - Output consumers.
+     */
+    forwardOutput(...listeners: ActOutputListener[]): this;
+    /**
+     * Invokes `act` with specified options.
+     *
+     * @param options - Options controlling this run, such as an abort signal
+     * @returns Workflow execution result for inspection
+     */
+    run(options?: ActProcessOptions): Promise<ActWorkflowExecResult>;
+    private validateRunnerParams;
+}
+export {};