GitHub Action
background-action
Run commands in the background with logging and failure detection. background-action
will send your processes to the background once a set of files, ports, sockets or http resources are available. It can optionally tail output until ready/timeout and/or log output stderr/stdout post-run.
Use background-action to bootstrap your system under test to eliminate workflow timeouts, race conditions, and test suite failures when the system fails to start. Specify the resources (http, file, tcp, socket) to wait-on
and how long to wait-for
before continuing to the next step. tail
stdout/stderr while you wait and/or log-output
post-run conditionally using log-output-if
.
What can happen when a system under test running in the background fails to start?
- No indication of the cause of failure
- Costly workflow timeouts
- Spurious test failures
- Lost log output
background-action
addresses these issues directly and was purpose-built to bootstrap your system under test in a discrete step to isolate failures at the source. We hope that it saves you and your team time and reduces frustration in these trying times.
Crafted with ❤️ by Jarvus Innovations in Philadelphia
jobs:
tests:
runs-on: ubuntu-latest
env:
API_PORT: 1212
steps:
- uses: actions/checkout@v4
- uses: JarvusInnovations/background-action@v1
name: Bootstrap System Under Test (SUT)
with:
run: |
npm install
PORT=$API_PORT node test/server.js &
PORT=2121 node test/server.js &
PORT=3232 node test/server.js &
# your step-level and job-level environment variables are available to your commands as-is
# npm install will count towards the wait-for timeout
# whenever possible, move unrelated scripts to a different step
# to background multiple processes: add & to the end of the command
wait-on: |
http://localhost:${{ env.API_PORT }}
http-get://localhost:2121
tcp:localhost:3232
file://very-important-secrets.txt
# IMPORTANT: to use environment variables in wait-on, you must use this form: ${{ env.VAR }}
# See wait-on section below for all resource types and prefixes
tail: true # true = stderr,stdout
# This will allow you to monitor the progress live
log-output-resume: stderr
# Eliminates previously output stderr log entries from post-run output
wait-for: 5m
log-output: stderr,stdout # same as true
log-output-if: failure
# failure = exit-early or timeout
working-directory: backend
# sets the working directory (cwd) for the shell running commands
- name: Tests that require the resources defined above to run
run: npm test
Parameter | Description | Allowed Values | Default |
---|---|---|---|
run |
Commands to run, supports multiple lines | ||
wait-on |
What resources to wait for: http|tcp|file|socket|unix:// |
See wait-on below |
|
wait-for |
How long to wait for (default unit: ms ) |
#ms, #s/sec, #m/min, #h/hr |
5m |
tail |
Which outputs to tail while you wait | stderr,stdout,true,false |
stderr,stdout |
log-output |
Which outputs to log post-run (after the job) | stderr,stdout,true,false |
stderr,stdout |
log-output-resume |
Which outputs should resume where tail left off (no duplicate lines) | stderr,stdout,true,false |
stderr,stdout |
log-output-if |
Whether or not to log output | failure,exit-early,timeout,success,true,false |
|
working-directory |
Sets the working directory (cwd) for the shell running commands |
background-action
leverages the handy wait-on package to control flow. You can pass any number of resources in the wait-on
configuration parameter separated by commas or newlines. For advanced use cases, such as: client-side SSL certs, authorization, proxy configuration and/or custom http headers you can provide a JSON serialized configuration object that matches wait-on's node.js api usage.
Prefix | Description | Example |
---|---|---|
file: |
Regular file (also default type) | file:/path/to/file |
http: |
HTTP HEAD returns 2XX response | http://m.com:90/foo |
https: |
HTTPS HEAD returns 2XX response | https://my/bar |
http-get: |
HTTP GET returns 2XX response | http://m.com:90/foo |
https-get: |
HTTPS GET returns 2XX response | https://my/bar |
tcp: |
TCP port is listening | 1.2.3.4:9000 or foo.com:700 |
socket: |
Domain Socket is listening | socket:/path/to/sock |
http://unix: |
http: over socket | http://unix:SOCK_PATH:URL_PATH |
http-get://unix: |
http-get: over socket | http-get://unix:/path/to/sock:/foo/bar |
See the actions tab for runs of this action! 🚀