@endbug/jest-pr-reporter

Jest PR Reporter

An opinionated Jest reporter that creates GitHub PR comments with test results.

Features

• ✅ Creates GitHub PR comments with test results
• ✅ Updates existing comments automatically
• ✅ Shows detailed test failure information
• ✅ Configurable footers for success/failure cases

Installation

npm install @endbug/jest-pr-reporter
# or
yarn add @endbug/jest-pr-reporter

Configuration

Add the reporter to your Jest configuration:

// jest.config.js
module.exports = {
  reporters: [
    "default",
    [
      "@endbug/jest-pr-reporter",
      {
        githubToken: process.env.GITHUB_TOKEN,
        owner: process.env.GITHUB_REPOSITORY_OWNER,
        repo:
          process.env.GITHUB_REPOSITORY &&
          process.env.GITHUB_REPOSITORY.split("/")[1],
        prNumber: Number(process.env.PR_NUMBER), // Set this in your workflow or pass as env
        sha: process.env.GITHUB_SHA,
        workspace: process.env.GITHUB_WORKSPACE, // optional
        workflowRunId: process.env.GITHUB_RUN_ID,
        jobName: process.env.GITHUB_JOB,
        footerSuccess: "🎉 All tests passed!",
        footerFailed: "❌ Please fix the failing tests.",
        hideProjectTag: false, // optional, defaults to false
        failOnError: false, // optional, defaults to false
      },
    ],
  ],
};

Options

Option	Type	Required	Description
githubToken	string	✅	GitHub personal access token or GitHub App token
owner	string	✅	GitHub repository owner (username or organization)
repo	string	✅	GitHub repository name
prNumber	number	✅	Pull request number
sha	string	✅	Commit SHA for linking to specific files
workflowRunId	string	✅	GitHub workflow run ID for linking to the specific run
jobName	string	✅	GitHub job name (numeric ID is automatically extracted)
workspace	string	❌	Workspace path for normalizing test file paths
footerSuccess	string	❌	Custom footer text when tests pass
footerFailed	string	❌	Custom footer text when tests fail
hideProjectTag	boolean	❌	Whether to hide the project attribution tag
failOnError	boolean	❌	Whether to fail the build if comment creation fails
header	string	❌	Custom string to append to the HTML comment header

Usage Examples

Basic Usage

// jest.config.js
module.exports = {
  reporters: [
    "default",
    [
      "@endbug/jest-pr-reporter",
      {
        githubToken: process.env.GITHUB_TOKEN,
        owner: "EndBug",
        repo: "jest-pr-reporter",
        prNumber: 1,
        sha: process.env.GITHUB_SHA,
        workflowRunId: process.env.GITHUB_RUN_ID,
        jobName: process.env.GITHUB_JOB,
      },
    ],
  ],
};

With Custom Footers

// jest.config.js
module.exports = {
  reporters: [
    "default",
    [
      "@endbug/jest-pr-reporter",
      {
        githubToken: process.env.GITHUB_TOKEN,
        owner: "EndBug",
        repo: "jest-pr-reporter",
        prNumber: 1,
        sha: process.env.GITHUB_SHA,
        workflowRunId: process.env.GITHUB_RUN_ID,
        jobName: process.env.GITHUB_JOB,
        footerSuccess: "🎉 Tests are passing! You can merge this PR.",
        footerFailed:
          "❌ Please review and fix the failing tests before merging.",
      },
    ],
  ],
};

With Custom Header

// jest.config.js
module.exports = {
  reporters: [
    "default",
    [
      "@endbug/jest-pr-reporter",
      {
        githubToken: process.env.GITHUB_TOKEN,
        owner: "EndBug",
        repo: "jest-pr-reporter",
        prNumber: 1,
        sha: process.env.GITHUB_SHA,
        workflowRunId: process.env.GITHUB_RUN_ID,
        jobName: process.env.GITHUB_JOB,
        header: "my-tests", // Results in: <!-- Sticky Pull Request Comment jest-pr-reporter: my-tests -->
      },
    ],
  ],
};

Advanced Configuration with Environment Variables

For more complex setups, you can separate the reporter options and use environment variables:

// jest.config.js
/** @type {import('@endbug/jest-pr-reporter').ReporterOptions} */
const reporterOptions = {
  githubToken: process.env.GH_TOKEN,
  owner: process.env.GITHUB_REPOSITORY_OWNER,
  repo:
    process.env.GITHUB_REPOSITORY &&
    process.env.GITHUB_REPOSITORY.split("/")[1],
  prNumber: Number(process.env.PR_NUMBER),
  sha: process.env.GITHUB_SHA,
  workspace: process.env.GITHUB_WORKSPACE,
  workflowRunId: process.env.GITHUB_RUN_ID,
  jobName: process.env.GITHUB_JOB,
  header: "jest-tests",
  footerFailed: `## 🛠️ Next Steps

1. **Review** the failing tests above
2. **Fix** your files so that the tests pass
3. **Push changes** and ensure CI passes

> [!TIP]
> Need help? Check the [README](https://github.com/campus-experts/campus-experts.github.io#readme) or ask in the Discord.
`.trim(),
};

module.exports = {
  preset: "ts-jest",
  testEnvironment: "node",
  reporters:
    process.env.CI === "true"
      ? [["@endbug/jest-pr-reporter", reporterOptions], "summary"]
      : ["default"],
};

In GitHub Actions

# .github/workflows/test.yml
name: Tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "18"
      - run: npm ci
      - run: npm test
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}

Examples

Check the examples/ directory for more detailed examples:

• jest-config-example.js - JavaScript configuration with environment variables
• jest-config-example.ts - TypeScript configuration with proper typing
• using-metadata.test.ts - Examples of using metadata in tests
• metadata-merging.test.ts - Examples of metadata inheritance and merging

How It Works

The reporter:

1. Runs after Jest completes all tests
2. Creates a detailed comment with test results
3. Shows passing/failing test counts and summaries
4. Links to specific test files and line numbers
5. Includes links to the specific workflow run for traceability
6. Updates existing comments automatically
7. Provides configurable footers for different scenarios
8. Uses HTML comments with customizable headers for comment identification

License

MIT