@global-data-analytics/gha-test

TypeScript library for testing GitHub Actions workflows with detailed reporting and assertions.

Features

• 🔍 GitHub API Integration - Fetch workflow runs, jobs, steps, and artifacts
• ✅ Rich Assertions - Test jobs, steps, artifacts, and JFrog deployments
• 📊 Detailed Reporting - Generate markdown reports for GitHub Actions summaries
• 🎯 Type-Safe - Full TypeScript support with type definitions
• 🧪 Jest Integration - Works seamlessly with Jest testing framework

Installation

npm install npm i gha-workflow-testing

Quick Start

1. Set Environment Variables

export GITHUB_TOKEN="your-github-token"
export GITHUB_REPOSITORY="owner/repo"

2. Write Tests

import { GitHubAPI, assertJobSuccess, getReporter } from 'gha-workflow-testing';

const WORKFLOW_NAME = 'CI Workflow';

describe('CI Workflow Tests', () => {
  let api: GitHubAPI;
  let runId: number;

  beforeAll(async () => {
    api = new GitHubAPI();
    const reporter = getReporter(WORKFLOW_NAME);

    runId = await api.getLatestRun(WORKFLOW_NAME);
    reporter.setRunId(runId);

    // Load all jobs and steps for comprehensive reporting
    await reporter.loadAllJobsAndSteps(api);
  });

  afterAll(() => {
    const reporter = getReporter();
    reporter.writeToGithubSummary();
    reporter.printReport();
  });

  it('should complete build job', async () => {
    const reporter = getReporter();
    const jobs = await api.getJobs(runId);

    assertJobSuccess(jobs, 'build', reporter, 'success');
  });
});

3. Run Tests

npm test

API Reference

GitHubAPI

Class for interacting with the GitHub API.

const api = new GitHubAPI();

// Get latest workflow run
const runId = await api.getLatestRun('My Workflow');

// Get jobs in a run
const jobs = await api.getJobs(runId);

// Wait for jobs to complete (optional - usually not needed with workflow_run trigger)
await api.waitForJobsCompletion(runId, timeout, pollInterval);

// Get steps in a job
const steps = await api.getSteps(runId, 'job-name');

// Get artifacts
const artifacts = await api.getArtifacts(runId);

Assertions

Functions for testing workflow components.

| Function | Parameters | Description | |----------|------------|-------------| | assertJobSuccess | jobs, jobName, reporter, expectedConclusion? | Assert a job completed with the expected conclusion (default: 'success') | | assertStepSuccess | steps, stepName, jobName, reporter, expectedConclusion? | Assert a step completed with the expected conclusion (default: 'success') | | assertArtifactExists | artifacts, artifactName, reporter | Assert that an artifact was uploaded in the workflow run | | assertJFrogArtifactExists | options, reporter | Assert that an artifact exists in JFrog Artifactory |

Usage Examples

// Assert job completed with expected conclusion
assertJobSuccess(jobs, 'job-name', reporter, 'success');

// Assert step completed successfully
assertStepSuccess(steps, 'step-name', 'job-name', reporter, 'success');

// Assert artifact exists
assertArtifactExists(artifacts, 'artifact-name', reporter);

// Assert JFrog artifact exists
await assertJFrogArtifactExists({
  jfrogUrl: 'URL',
  repository: 'REPO_NAME',
  artifactPath: 'apps/your-app',
  artifactName: 'dev',
  jfrogToken: process.env.JFROG_TOKEN,
  reporter,
});

Reporter

Class for generating test reports.

const reporter = getReporter('Workflow Name');

// Set run ID
reporter.setRunId(runId);

// Load all jobs and steps for complete visibility
await reporter.loadAllJobsAndSteps(api);

// Record test results (done automatically by assertions)
reporter.recordJobTest('job-name', true, 'success', 'success');
reporter.recordStepTest('job-name', 'step-name', true, 'success', 'success');
reporter.recordArtifactTest('artifact-name', 'exists', true, 'expected');

// Generate and write report
reporter.writeToGithubSummary(); // Write to GitHub Actions summary
reporter.printReport(); // Print to console

Project Structure

dops-gha-tests/
├── src/
│   ├── github-api.ts      # GitHub API client
│   ├── assertions.ts      # Test assertions
│   ├── reporter.ts        # Test reporter
│   └── index.ts           # Main exports
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

This will compile TypeScript to JavaScript in the dist/ directory.

Development

# Install dependencies
npm install

# Lint code
npm run lint

# Format code
npm run format

# Build
npm run build

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GITHUB_TOKEN | Yes | GitHub API token with workflow read access | | GITHUB_REPOSITORY | Yes | Repository in owner/repo format | | GITHUB_STEP_SUMMARY | No | Path to GitHub Actions summary file (auto-set in CI) | | JFROG_TOKEN | No | JFrog access token for artifact verification |

Example Usage

• TBA

License

MIT

Maintainers

Rohit Patil