Locally verifying GitHub Actions Job Summaries

GitHub Actions Job Summaries are a great way to provide more information on your job’s output. This summary is shown in the Actions tab of your repository.

Show image

In this post, I’ll explain how you can locally develop and test your GitHub Actions Job Summary outputs using the @actions/core dependency.

In my case, I used this approach to develop the GitHub Actions Reporter for Playwright. This npm package generates a summary output for your Playwright tests.

How to write a summary output

The easiest way to write a GitHub Actions summary is to use the @actions/core dependency. The @actions/core dependency provides functions for inputs, outputs, logging, and more.

You can write the job summary using the core.summary methods. Once completed, you can call the core.summary.write() method to write the buffer to the Job Summary output on GitHub Actions.

1
import * as core from '@actions/core';
2

3
const summary = core.summary;
4

5
summary.addHeading("My job summary heading", 1);
6
summary.addSeparator();
7

8
summary.addList(['item1','item2','item3'], true);
9

10
await summary.write();

The downside of this approach is that you have to push your changes to GitHub to see if your summary output is working as expected. When you try to run it locally, it will throw an error saying it is unable to find the GITHUB_STEP_SUMMARY environment variable.

Testing your summary locally

To test your summary locally, you must set the GITHUB_STEP_SUMMARY environment variable. This variable defines the file path where the summary output should be written. Locally, we can pass a local file path to this environment variable.

Here is an example of how to set the GITHUB_STEP_SUMMARY environment variable when running your script locally.

1
import * as core from '@actions/core';
2
import { join } from "path";
3
import { existsSync, unlinkSync, writeFileSync } from "fs";
4

5
const __dirname = import.meta.dirname;
6

7
if (process.env.NODE_ENV === "development") {
8
  const summaryFile = join(__dirname, "summary.html");
9
  if (existsSync(summaryFile)) {
10
    unlinkSync(summaryFile);
11
  }
12
  writeFileSync(summaryFile, "", "utf-8");
13
  process.env.GITHUB_STEP_SUMMARY = summaryFile;
14
  process.env.GITHUB_ACTIONS = "true";
15
}
16

17
const summary = core.summary;
18

19
summary.addHeading("My job summary heading", 1);
20
summary.addSeparator();
21

22
summary.addList(['item1','item2','item3'], true);
23

24
await summary.write();

When you run your script locally, you will see that the summary.html file is created with the content of your summary output. The generated file contents look like this:

1
<h1>My job summary heading</h1>
2
<hr>
3
<ol><li>item1</li><li>item2</li><li>item3</li></ol>