github-action-ts-run-api v3.0.4
TypeScript API for GitHub Action execution and integration/functional testing
Purpose
š¶ Execute your GitHub action locally (or at any other environment).
š¶ Write integration and functional tests for an action, run them locally and on CI.
š¶ Have a short feedback loop without pushing and checking an action behaviour at real GitHub runners every time you change it.
Features
ā Supports executing JavaScript and Docker actions.
ā Tested under Windows, Linux and macOS (Intel + Apple Silicon), NodeJS >= 12 locally and on GitHub hosted runners.
ā Works well with Docker Desktop under Windows and macOS.
ā Can be used together with any JavaScript test frameworks or alone.
ā
Can execute an explicitly specified JS file or main, pre, post script from action.yml
.
ā Can execute a separate sync or async JS function, isolating its environment (process env, exitCode and working dir), intercepting stdout and stderr output for effective dependencies mocking.
ā Has a clear JavaScript API with TypeScript declarations and reasonable defaults
ā Produces warnings about deprecated Actions commands
Setting up an action run option includes:
- Inputs. Can read default input values from
action.yml
- Saved state
- Custom environment variables
- GitHub context
- GitHub service environment variables
- Faking GitHub service files (file commands, event payload file)
- Faking GitHub dirs (workflow, workspace, temp)
Reading results of an action run includes:
- Reading exit code, stdout and stderr
- Reading outputs, saved state, warnings, errors, notices and secrets from intercepted stdout
- Reading exported vars, added paths from faked file commands
Installation
Install for use in tests
npm i github-action-ts-run-api --save-dev
Documentation
- Run targets overview
- Run options
- Run result
- Run result warnings (new! starting from 2.3.0)
Other information:
- Testing of GitHub Actions article.
Quick examples
Test JS action in a child node process
name: 'test'
# ...
runs:
using: 'node16'
main: 'main.js'
const core = require("@actions/core");
const context = require('@actions/github').context;
const fs = require('fs');
core.addPath('newPath');
fs.writeFileSync(
path.join(process.env.RUNNER_TEMP, 'f.txt'),
context.payload.pull_request.number.toString()
);
action.test.ts:
import {RunOptions, RunTarget} from 'github-action-ts-run-api';
// You can also test "pre" and "post" scripts
const target = RunTarget.mainJsScript('action.yml');
const options = RunOptions.create()
// Internally, runner will fake a json file to be picked by @actions/github
.setGithubContext({payload: {pull_request: {number: 123}}})
// By default, RUNNER_TEMP is faked for a run and then deleted. Keep it
.setFakeFsOptions({rmFakedTempDirAfterRun: false});
const res = await target.run(options);
try {
assert(res.commands.addedPaths === ['newPath']);
// somewhere in system temp dir
const pathOfCreatedFile = path.join(res.tempDirPath, 'f.txt');
// check the contents of a file saved by tested action
assert(fs.readFileSync(pathOfCreatedFile).toString() === '123');
} finally {
// we should do it manually because we set rmFakedTempDirAfterRun: false
// otherwise it is deleted at the end of target.run()
res.cleanUpFakedDirs();
// With Jest you can use this instead:
// This code also gets executed on test timeout
// afterAll(() => {
// deleteAllFakedDirs();
// });
}
Test JavaScript function in isolated Action environment
const core = require("@actions/core");
export async function actionMainFn() {
core.setOutput('out1', core.getInput('in1'));
core.setOutput('out2', process.env.ENV2);
core.exportVariable('v3', core.getState('my_state'));
// writes to errors and sets process.exitCode to 1
return new Promise(resolve => setTimeout(() => {
core.setFailed('err1');
resolve();
}, 1000));
}
main.test.ts:
import {RunOptions, RunTarget} from 'github-action-ts-run-api';
import {actionMainFn} from './main.js';
// Will wait until returned promise fulfills.
// Use RunTarget.syncFn() for regular functions
const target = RunTarget.asyncFn(actionMainFn);
const options = RunOptions.create()
.setInputs({in1: 'abc'})
.setEnv({ENV2: 'def'})
.setState({my_state: 'ghi'});
const result = await target.run(options);
assert(result.durationMs >= 1000);
assert(result.commands.outputs === {out1: 'abc', out2: 'def'});
assert(result.commands.exportedVars === {v3: 'ghi'});
assert(result.exitCode === 1);
assert(result.runnerWarnings.length === 0);
// changes were isolated inside a function run
assert(process.exitCode !== 1);
assert(result.commands.errors === ['err1']);
Test Docker action
import {RunOptions, RunTarget} from 'github-action-ts-run-api';
const target = RunTarget.dockerAction('action.yml');
const options = RunOptions.create()
.setInputs({input1: 'val1', input2: 'val2'})
.setEnv({ENV1: 'val3'})
.setWorkingDir('/dir/inside/container')
.setTimeoutMs(5000)
// ...
const res = await target.run(options);
console.log(
res.commands.outputs,
res.commands.exportedVars,
res.isSuccessBuild,
res.isSuccess,
res.isTimedOut
);
Integration tests examples:
You can find examples for the complicated cases in the library integration tests:
Also, check out real actions integration tests: