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.

Purpose

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

Usage

Example

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

Configuration

wait-on

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.

Resource Types

See the actions tab for runs of this action! :rocket: