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

$3

* 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)

$3

* 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
* Single function target
* JavaScript file target
* Docker target
- Run options
- Run result
- Run result warnings (new! starting from 2.3.0)

$3

* Testing of GitHub Actions article.

Quick examples

$3

action.test.ts:
`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();
// });
}
`

$3

main.test.ts:
`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']);
`

$3

`ts
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
);
``

$3

You can find examples for the complicated cases in the library integration tests:
* Docker target test
* JS file target test
* Function target test

Also, check out real actions integration tests:

* git-get-release-action
* schema-validator-action
* js-eval-action