### Install Dependencies with npm

Source: https://github.com/pshevche/act-test-runner/blob/main/README.md

This command installs the project's dependencies using npm, which is a necessary step before running any development or verification tasks. It ensures all required packages are available in the project's `node_modules` directory.

```bash
npm install
```

--------------------------------

### Define Workflow Event Trigger with JavaScript

Source: https://github.com/pshevche/act-test-runner/blob/main/README.md

This example shows how to define a specific event (e.g., 'pull_request' type 'opened') to trigger a GitHub workflow and assert that the correct event type is logged in the job's output. It uses `withEvent` to specify the trigger.

```javascript
test('custom workflow with event', async () => {
  const result = await new ActRunner()
    .withWorkflowBody(
      `
name: Workflow printing the event_type
on:
  pull_request:
    types: [opened]
  issues:
    types: [opened]

jobs:
  print_event_type:
    runs-on: ubuntu-latest
    steps:
      - name: Print event type
        run: |
          echo "Event type: ${{ github.event_name }}"
  `,
    )
    .withEvent('pull_request')
    .run();

  expect(result.status).toBe(ActExecStatus.SUCCESS);
  const job = result.job('print_event_type')!;
  expect(job.status).toBe(ActExecStatus.SUCCESS);
  expect(job.output).toContain('Event type: pull_request');
});
```

--------------------------------

### ActRunnerError - Handling Configuration Errors

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Custom error class thrown when the `ActRunner` is misconfigured or encounters an unexpected issue during setup or execution. This allows for specific error handling, such as catching invalid configurations.

```typescript
import { ActRunner, ActRunnerError } from '@pshevche/act-test-runner';

try {
  // This will throw - cannot set both workflowFile and workflowBody
  await new ActRunner()
    .withWorkflowFile('.github/workflows/ci.yml')
    .withWorkflowBody('name: test
on: [push]')
    .run();
} catch (error) {
  if (error instanceof ActRunnerError) {
    console.error('Runner configuration error:', error.message);
  }
}
```

--------------------------------

### Configure Artifact Server with ArtifactServer

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Sets up a local artifact server for workflows using `actions/upload-artifact`. This enables testing artifact uploading and downloading locally.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';
import { existsSync } from 'node:fs';
import { join } from 'node:path';

const artifactDir = '/tmp/act-artifacts';

const result = await new ActRunner()
  .withWorkflowBody(`
    name: Artifact workflow
    on: [push]
    jobs:
      upload:
        runs-on: ubuntu-latest
        steps:
          - run: echo "artifact content" > output.txt
          - uses: actions/upload-artifact@v3
            with:
              name: my-artifact
              path: output.txt
  `)
  .withArtifactServer(artifactDir)
  .withEnvValues(['ACTIONS_RUNTIME_TOKEN', 'token'])  // Required for upload-artifact
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
expect(existsSync(join(artifactDir, '1', 'my-artifact'))).toBe(true);
```

--------------------------------

### Run Verification Tasks with npm

Source: https://github.com/pshevche/act-test-runner/blob/main/README.md

This command executes the verification tasks defined in the project's `package.json` scripts, typically used for linting, testing, or building. It's a standard way to ensure the project's code quality and functionality.

```bash
npm run check
```

--------------------------------

### Configure Cache Server with CacheServer

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Sets up a local cache server for workflows using `actions/cache`. This allows you to test caching mechanisms locally without relying on external services.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';
import { existsSync } from 'node:fs';
import { join } from 'node:path';

const cacheDir = '/tmp/act-cache';

const result = await new ActRunner()
  .withWorkflowBody(`
    name: Cache workflow
    on: [push]
    jobs:
      cache_deps:
        runs-on: ubuntu-latest
        steps:
          - name: Create file
            run: echo "cached content" > cached-file.txt
          - name: Cache file
            uses: actions/cache@v3
            with:
              path: cached-file.txt
              key: my-cache-key
  `)
  .withCacheServer(cacheDir)
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
// Cache artifacts are stored in the specified directory
expect(existsSync(join(cacheDir, 'cache'))).toBe(true);
```

--------------------------------

### Assert Workflow Execution with JavaScript

Source: https://github.com/pshevche/act-test-runner/blob/main/README.md

This snippet demonstrates how to execute a GitHub workflow defined directly as a string and assert its success status, output, and the number of jobs run. It utilizes the ActRunner class to run the workflow and the expect function for assertions.

```javascript
test('custom workflow', async () => {
  const result = await new ActRunner()
    .withWorkflowBody(
      `
name: Simple passing workflow
on: [push]

jobs:
  successful_job:
    runs-on: ubuntu-latest
    steps:
      - name: Successful step
        run: echo "Hello, World!"
  `,
    )
    .run();

  expect(result.status).toBe(ActExecStatus.SUCCESS);
  expect(result.output).toContain('Hello, World!');
  expect(result.jobs.size).toBe(1);

  const successfulJob = result.job('successful_job')!;
  expect(successfulJob.status).toBe(ActExecStatus.SUCCESS);
  expect(successfulJob.output).toContain('Hello, World!');
});
```

--------------------------------

### Set Workflow Inputs with JavaScript

Source: https://github.com/pshevche/act-test-runner/blob/main/README.md

This snippet demonstrates how to pass environment variables as inputs to a GitHub workflow using the `withEnvValues` method. It then asserts that the workflow correctly uses these inputs to produce the expected output.

```javascript
test('custom workflow with inputs', async () => {
  const result = await new ActRunner()
    .withWorkflowBody(
      `
name: Simple workflow printing a couple of environment variables
on: [push]

jobs:
  print_greeting:
    runs-on: ubuntu-latest
    steps:
      - name: Print greeting from env variables
        run: echo "$GREETING, $NAME!"
  `,
    )
    .withEnvValues(['GREETING', 'Hello'], ['NAME', 'Bruce'])
    .run();

  expect(result.status).toBe(ActExecStatus.SUCCESS);
  const job = result.job('print_greeting')!;
  expect(job.status).toBe(ActExecStatus.SUCCESS);
  expect(job.output).toContain('Hello, Bruce!');
});
```

--------------------------------

### withWorkingDir() - Set Working Directory

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Specifies a custom working directory for the runner's temporary files instead of using the system temp folder.

```APIDOC
## withWorkingDir()

### Description
Specifies a custom working directory for the runner's temporary files instead of using the system temp folder.

### Method
Chaining method on ActRunner instance

### Endpoint
N/A (Method on ActRunner)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkingDir('/tmp/my-test-workspace')
  .withWorkflowBody(`
    name: Custom dir workflow
    on: [push]
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - run: echo "Building in custom workspace"
  `)
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
```

### Response
#### Success Response (200)
N/A (Method returns ActRunner instance for chaining)

#### Response Example
N/A
```

--------------------------------

### withAdditionalArgs() - Pass Extra CLI Arguments

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Passes additional command-line arguments directly to the `act` executable for advanced configuration.

```APIDOC
## withAdditionalArgs()

### Description
Passes additional command-line arguments directly to the `act` executable for advanced configuration.

### Method
Chaining method on ActRunner instance

### Endpoint
N/A (Method on ActRunner)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowFile('.github/workflows/ci.yml')
  .withAdditionalArgs('--insecure-secrets', '--verbose', '--container-architecture', 'linux/amd64')
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
```

### Response
#### Success Response (200)
N/A (Method returns ActRunner instance for chaining)

#### Response Example
N/A
```

--------------------------------

### Run Workflow from File - TypeScript

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Executes a GitHub Actions workflow specified by its file path. This method is ideal for testing existing workflow files within a repository. The function returns an execution result object that includes the overall status, console output, and individual job outcomes.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowFile('.github/workflows/ci.yml')
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
expect(result.job('build')?.status).toBe(ActExecStatus.SUCCESS);
expect(result.job('test')?.status).toBe(ActExecStatus.SUCCESS);

```

--------------------------------

### Set Working Directory with withWorkingDir()

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Specifies a custom working directory for the runner's temporary files. This is useful for isolating test environments and managing temporary data. It takes a string path as an argument.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkingDir('/tmp/my-test-workspace')
  .withWorkflowBody(`
    name: Custom dir workflow
    on: [push]
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - run: echo "Building in custom workspace"
  `)
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
```

--------------------------------

### Configure GitHub Secrets with SecretsValues and SecretsFile

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Configures GitHub secrets for workflow execution using `withSecretsValues` or `withSecretsFile`. Note: Use `--insecure-secrets` flag to see secret values in output. This method is useful for providing sensitive information to your workflows.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowBody(`
    name: Secrets workflow
    on: [push]
    jobs:
      use_secrets:
        runs-on: ubuntu-latest
        steps:
          - run: echo "${{ secrets.API_KEY }}"
  `)
  .withSecretsValues(['API_KEY', 'super-secret-key'], ['DB_PASSWORD', 'db-pass'])
  .withAdditionalArgs('--insecure-secrets')  // Required to see secrets in output
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
expect(result.job('use_secrets')?.output).toContain('super-secret-key');
```

--------------------------------

### Configure Workflow Variables with VariablesValues and VariablesFile

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Configures GitHub workflow variables (vars context) for workflow execution using `withVariablesValues` or `withVariablesFile`. This allows you to pass non-sensitive configuration data to your workflows.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowBody(`
    name: Variables workflow
    on: [push]
    jobs:
      print_vars:
        runs-on: ubuntu-latest
        steps:
          - run: echo "${{ vars.GREETING }}, ${{ vars.NAME }}!"
  `)
  .withVariablesValues(['GREETING', 'Hello'], ['NAME', 'World'])
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
expect(result.job('print_vars')?.output).toContain('Hello, World!');
```

--------------------------------

### Configure Action Inputs with InputsValues and InputsFile

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Configures input values for reusable workflows or `workflow_dispatch` triggers using `withInputsValues` or `withInputsFile`. This is essential when testing workflows that accept inputs.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowBody(`
    name: Input workflow
    on:
      workflow_dispatch:
        inputs:
          name:
            required: true
            type: string
    jobs:
      greet:
        runs-on: ubuntu-latest
        steps:
          - run: echo "Hello, ${{ inputs.name }}!"
  `)
  .withInputsValues(['name', 'Developer'])
  .withEvent('workflow_dispatch')
  .run();

expect(result.job('greet')?.output).toContain('Hello, Developer!');
```

--------------------------------

### forwardOutput() - Stream Output to Console

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Forwards the act execution output to the console in real-time for debugging purposes.

```APIDOC
## forwardOutput()

### Description
Forwards the act execution output to the console in real-time for debugging purposes.

### Method
Chaining method on ActRunner instance

### Endpoint
N/A (Method on ActRunner)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowFile('.github/workflows/ci.yml')
  .forwardOutput()  // Streams output to console as workflow runs
  .run();

// Output is also available in result after completion
console.log(result.output);
```

### Response
#### Success Response (200)
N/A (Method returns ActRunner instance for chaining)

#### Response Example
N/A
```

--------------------------------

### Stream Output to Console with forwardOutput()

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Forwards the `act` execution output to the console in real-time. This is invaluable for debugging and monitoring the progress of your workflows during local testing. It's a simple method call with no arguments.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowFile('.github/workflows/ci.yml')
  .forwardOutput()  // Streams output to console as workflow runs
  .run();

// Output is also available in result after completion
console.log(result.output);
```

--------------------------------

### Configure Matrix Values with Matrix

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Restricts matrix job execution to specific value combinations using `withMatrix` instead of running all permutations. This is useful for testing specific scenarios within a matrix strategy.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

// Run specific matrix combination
const result = await new ActRunner()
  .withWorkflowBody(`
    name: Matrix workflow
    on: [push]
    jobs:
      build:
        runs-on: ubuntu-latest
        strategy:
          matrix:
            os: [ubuntu, windows]
            node: [16, 18, 20]
        steps:
          - run: echo "OS: ${{ matrix.os }}, Node: ${{ matrix.node }}"
  `)
  .withMatrix(['os', 'ubuntu'], ['node', '18'])
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
expect(result.job('build')?.output).toContain('OS: ubuntu, Node: 18');
```

--------------------------------

### Pass Extra CLI Arguments with withAdditionalArgs()

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Passes additional command-line arguments directly to the `act` executable. This allows for advanced configuration and customization of the `act` runner. It accepts a variable number of string arguments.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowFile('.github/workflows/ci.yml')
  .withAdditionalArgs('--insecure-secrets', '--verbose', '--container-architecture', 'linux/amd64')
  .run();

expect(result.status).toBe(ActExecStatus.SUCCESS);
```

--------------------------------

### Run Workflow from Inline Body - TypeScript

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Executes a GitHub Actions workflow defined directly as a string. This is useful for testing specific workflow logic in isolation without needing a separate file. It returns an execution result object containing status, output, and job details.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

const result = await new ActRunner()
  .withWorkflowBody(
    `
    name: Simple workflow
    on: [push]
    jobs:
      greet:
        runs-on: ubuntu-latest
        steps:
          - name: Say hello
            run: echo "Hello, World!"
  `
  )
  .run();

console.log(result.status);           // ActExecStatus.SUCCESS or ActExecStatus.FAILED
console.log(result.output);           // Full workflow console output
console.log(result.jobs.size);        // Number of jobs executed
console.log(result.job('greet')?.output);  // Output from specific job

```

--------------------------------

### ActRunnerError - Configuration Error

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Error thrown when the ActRunner is misconfigured or encounters an unexpected error during execution.

```APIDOC
## ActRunnerError

### Description
Error thrown when the ActRunner is misconfigured or encounters an unexpected error during execution.

### Example Usage
```typescript
import { ActRunner, ActRunnerError } from '@pshevche/act-test-runner';

try {
  // This will throw - cannot set both workflowFile and workflowBody
  await new ActRunner()
    .withWorkflowFile('.github/workflows/ci.yml')
    .withWorkflowBody('name: test\non: [push]')
    .run();
} catch (error) {
  if (error instanceof ActRunnerError) {
    console.error('Runner configuration error:', error.message);
  }
}
```
```

--------------------------------

### Set Environment Variables - TypeScript

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Configures environment variables for the workflow execution. Variables can be provided directly as key-value pairs using `withEnvValues` or loaded from a file (in KEY=VALUE format) using `withEnvFile`. This is essential for testing workflows that rely on specific environment configurations.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

// Inline environment values
const result1 = await new ActRunner()
  .withWorkflowBody(
    `
    name: Env workflow
    on: [push]
    jobs:
      print_env:
        runs-on: ubuntu-latest
        steps:
          - run: echo "$GREETING, $NAME!"
  `
  )
  .withEnvValues(['GREETING', 'Hello'], ['NAME', 'Bruce'])
  .run();

expect(result1.status).toBe(ActExecStatus.SUCCESS);
expect(result1.job('print_env')?.output).toContain('Hello, Bruce!');

// From environment file (KEY=VALUE format)
const result2 = await new ActRunner()
  .withWorkflowFile('.github/workflows/print_env.yml')
  .withEnvFile('./tests/fixtures/env.config')
  .run();

```

--------------------------------

### Configure Trigger Event - TypeScript

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Sets the specific event that triggers the GitHub Actions workflow. This method can accept a simple event type string or a path to a JSON file containing the event payload. It's crucial for testing workflows that react to different GitHub events like pull requests or issue creations.

```typescript
import { ActRunner, ActExecStatus } from '@pshevche/act-test-runner';

// Simple event type
const result1 = await new ActRunner()
  .withWorkflowBody(
    `
    name: PR workflow
    on:
      pull_request:
        types: [opened]
      issues:
        types: [opened]
    jobs:
      handle_event:
        runs-on: ubuntu-latest
        steps:
          - run: echo "Event: ${{ github.event_name }}"
  `
  )
  .withEvent('pull_request')
  .run();

expect(result1.job('handle_event')?.output).toContain('Event: pull_request');

// With event payload file
const result2 = await new ActRunner()
  .withWorkflowFile('.github/workflows/pr-handler.yml')
  .withEvent('pull_request', './tests/fixtures/pr_payload.json')
  .run();

expect(result2.job('print_pr_title')?.output).toContain('PR Title: Example PR payload');

```

--------------------------------

### ActExecStatus - Execution Status Enum

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Enum representing the outcome of workflow or job execution.

```APIDOC
## ActExecStatus

### Description
Enum representing the outcome of workflow or job execution.

### Values
- **SUCCESS**: Execution completed successfully.
- **FAILED**: Execution failed.
- **SKIPPED**: Job was skipped (e.g., due to conditional).

### Example Usage
```typescript
import { ActExecStatus } from '@pshevche/act-test-runner';

// Available status values
ActExecStatus.SUCCESS   // Execution completed successfully
ActExecStatus.FAILED    // Execution failed
ActExecStatus.SKIPPED   // Job was skipped (e.g., due to conditional)

// Usage in assertions
expect(result.status).toBe(ActExecStatus.SUCCESS);
expect(result.job('conditional_job')?.status).toBe(ActExecStatus.SKIPPED);
```
```

--------------------------------

### ActWorkflowExecResult - Workflow Execution Result

Source: https://context7.com/pshevche/act-test-runner/llms.txt

The result object returned by `run()` containing workflow status, output, and job information.

```APIDOC
## ActWorkflowExecResult

### Description
The result object returned by `run()` containing workflow status, output, and job information.

### Properties
- **status** (ActExecStatus) - The overall status of the workflow execution.
- **output** (string) - The complete output from the workflow execution.
- **jobs** (Map<string, ActJobExecResult>) - A map of job names to their execution results.

### Methods
- **job(name: string)**: Returns the execution result for a specific job by name, or undefined if the job does not exist.

### Example Usage
```typescript
import { ActRunner, ActExecStatus, ActWorkflowExecResult } from '@pshevche/act-test-runner';

const result: ActWorkflowExecResult = await new ActRunner()
  .withWorkflowBody(`
    name: Multi-job workflow
    on: [push]
    jobs:
      job1:
        runs-on: ubuntu-latest
        steps:
          - run: echo "Job 1 output"
      job2:
        runs-on: ubuntu-latest
        steps:
          - run: exit 1
  `)
  .run();

// Workflow-level properties
expect(result.status).toBe(ActExecStatus.FAILED);  // FAILED if any job fails
expect(result.output).toContain('Job 1 output');    // Full workflow output
expect(result.jobs.size).toBe(2);                   // Number of jobs

// Individual job access
const job1 = result.job('job1')!;
expect(job1.name).toBe('job1');
expect(job1.status).toBe(ActExecStatus.SUCCESS);
expect(job1.output).toContain('Job 1 output');

const job2 = result.job('job2')!;
expect(job2.status).toBe(ActExecStatus.FAILED);
```
```

--------------------------------

### ActExecStatus - Execution Status Enum

Source: https://context7.com/pshevche/act-test-runner/llms.txt

An enumeration representing the possible outcomes of a workflow or job execution. It provides clear, standardized status codes for assertions and checks. Includes SUCCESS, FAILED, and SKIPPED.

```typescript
import { ActExecStatus } from '@pshevche/act-test-runner';

// Available status values
ActExecStatus.SUCCESS   // Execution completed successfully
ActExecStatus.FAILED    // Execution failed
ActExecStatus.SKIPPED   // Job was skipped (e.g., due to conditional)

// Usage in assertions
expect(result.status).toBe(ActExecStatus.SUCCESS);
expect(result.job('conditional_job')?.status).toBe(ActExecStatus.SKIPPED);
```

--------------------------------

### ActWorkflowExecResult - Workflow Execution Result Object

Source: https://context7.com/pshevche/act-test-runner/llms.txt

Represents the outcome of a workflow execution. It contains the overall status, detailed output, and information about individual jobs. This object is returned by the `run()` method.

```typescript
import { ActRunner, ActExecStatus, ActWorkflowExecResult } from '@pshevche/act-test-runner';

const result: ActWorkflowExecResult = await new ActRunner()
  .withWorkflowBody(`
    name: Multi-job workflow
    on: [push]
    jobs:
      job1:
        runs-on: ubuntu-latest
        steps:
          - run: echo "Job 1 output"
      job2:
        runs-on: ubuntu-latest
        steps:
          - run: exit 1
  `)
  .run();

// Workflow-level properties
expect(result.status).toBe(ActExecStatus.FAILED);  // FAILED if any job fails
expect(result.output).toContain('Job 1 output');    // Full workflow output
expect(result.jobs.size).toBe(2);                   // Number of jobs

// Individual job access
const job1 = result.job('job1')!;
expect(job1.name).toBe('job1');
expect(job1.status).toBe(ActExecStatus.SUCCESS);
expect(job1.output).toContain('Job 1 output');

const job2 = result.job('job2')!;
expect(job2.status).toBe(ActExecStatus.FAILED);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.