GitHub Action
Background Run & Test
A GitHub Action that allows you to execute testing commands (e.g., npm test)
while concurrently running background tasks (like starting a server). With
support for conditional waiting on resources, it simplifies workflows with
background jobs/works and integrate with the
wait-on library for waiting on
resources.
ℹ️ Notice
The code was derived from the cypress-io/github-action, but with a few additions and enhancements for more general usage.
- Background Tasks: Run a server or other background processes with
startcommands. - Cross-Platform Support: Tailored commands for Windows (
start-windows,command-windows). - Resource Wait: Wait for URLs, ports, files, or sockets to become available before testing.
- Conditional Logic: Use
wait-if,start-if, andcommand-iffor advanced flow control. - Custom Working Directory: Set a specific
working-directoryfor running commands in a defined path. - Multi-Command Support: Run multiple
startorcommandentries at once.
| Option | Description |
|---|---|
start |
Background command (Linux/Mac). |
start-windows |
Background command (Windows). |
command |
Main testing command (Linux/Mac). |
command-windows |
Main testing command (Windows). |
wait-on |
Resources to wait for (URLs, files, ports, etc.). |
wait-on-timeout |
Timeout in seconds for wait-on (default: 60). |
working-directory |
Directory to execute commands in. |
wait-if |
Conditional logic for resource waiting. |
start-if |
Conditional logic for starting background tasks. |
command-if |
Conditional logic for executing main commands. |
Run a Node.js server in the background while executing tests
name: Run Tests
on: [push]
jobs:
run-test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Run E2E Tests
uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
command: yarn run test:appsYou can also specify a build command before
name: Run Tests
on: [push]
jobs:
run-test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Run E2E Tests
uses: MohamedRaslan/background_run_and_test@v1
with:
start:
| #Or you can do it in a comma separated style like so "yarn run app:api, yarn run "app:web
yarn run app:api
yarn run app:web
command: yarn run generate:docs, yarn run test:appsSometimes on Windows you need to run a different start command. You can use
start-windows and command-windows parameter for this, which takes precedence
over the normal commands when on Windows.
name: Run Tests
on: [push]
jobs:
run-test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Run E2E Tests
uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
start-windows: yarn run start:apps:server:windows
command: yarn run test:apps
command-windows: yarn run tests:apps:windowsIf you want to set a specific directory where your commands are run, you can
specify the path via the working-directory option
name: Run Tests
on: [push]
jobs:
run-test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Run E2E Tests
uses: MohamedRaslan/background_run_and_test@v1
with:
working-directory: ./packages/example
start: yarn run start:apps:serverIf you are starting a local server and it takes a while to start, you can add a
parameter wait-on and pass URL to wait for the server to respond.
name: Run Tests
on: [push]
jobs:
run-test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Run E2E Tests
uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
wait-on: 'http://localhost:8080'
command: yarn run test:appsBy default, wait-on will retry for 60 seconds. You can pass a custom timeout in
seconds using wait-on-timeout.
- uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
wait-on: 'http://localhost:8080'
# wait for 2 minutes for the server to respond
wait-on-timeout: 120
command: yarn run test:appsYou can wait for multiple URLs to respond by separating URLs with a comma
- uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
wait-on: | #Or you can do it in a comma separated style like so 'http://localhost:8080, http://localhost:4000'
http://localhost:8080
http://localhost:4000
command: yarn run test:appsWait use wait-on and by defualt it wait for a HEAD response st, you can make it wait for GET response instead as follow
- uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
wait-on: 'http-get://localhost:8080, http://localhost:4000'
# This will wait for the GET response of the 1st one and HEAD response to the 2nd one
command: yarn run test:appsYou can also wait or not based on condtion using the wait-if
ℹ️ Note: By default it will wait
name: Run Tests
on: [push]
jobs:
run-test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Lint the app
id: lint
run: yarn run lint
- name: Run E2E Tests
uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
wait-if:
contains( github.base_ref , 'local' ) || ${{ failure() &&
steps.lint.outcome == 'failure' }}
command: yarn run test:appsSimilarly, You can also wait or not based on condition using the start-if ,
and command-if
ℹ️ Note: By default it will run the commands
name: Run Tests
on: [push]
jobs:
run-test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Lint the app
id: lint
run: yarn run lint
- name: Run E2E Tests
uses: MohamedRaslan/background_run_and_test@v1
with:
start: yarn run start:apps:server
start-if:
contains( github.base_ref , 'local' ) || ${{ failure() &&
steps.lint.outcome == 'failure' }}
wait-if:
contains( github.base_ref , 'local' ) || ${{ failure() &&
steps.lint.outcome == 'failure' }}
command: yarn run test:apps
command-if:
contains( github.base_ref , 'local' ) || ${{ failure() &&
steps.lint.outcome == 'failure' }}The action integrate with the wait-on
package to control the flow. You can pass any number of resources in the
wait-on configuration parameter separated by commas or newlines.
Exaples can be found here wait-on cli usage
If you encounter any problems, please file an issue along with a detailed description.
Contributions are very welcome ❤️.