Background Run & Test GitHub Action

GitHub Action to run a commands (e.g. a test) while also running another commands (e.g. a server) in the background, And you could conditional wait for the background resources to be available the wait-on use the wait-on Yarn package under the hood so most of the waiton functionality should be accepted.

ℹ️ Notice

• The code was derived from the cypress-io/github-action, but with a few additions and enhancements for more general usage.
• Intial vesion (v1.0.0) not tested very well, but the following versions should be more tested and muture.

😉 Features

The action lets you dow the following:

• Run a command or command-windows in the background to open a server or do some background tasks while running your tests
• Optionally wait for resources before running your test, your resources could be (files, ports, sockets, or http(s) resources to become available (or not available using reverse mode)) as it use the wait-on Yarn package under the hood
• Conditional wait using the wait-if option
• You can run multiple commands at once

Usage

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:apps:server
          command: yarn run test:apps

Multiple commands command

You 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: yarn run app:api, yarn run app:web
          command: yarn run generate:docs, yarn run test:apps

Windows

Sometimes 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:apps:server
          start-windows: yarn run start:apps:server:windows
          command: yarn run test:apps
          command-windows: yarn run tests:apps:windows

Current working directory

If you want to set a specific directory where your commands are run, you can specify the path via the cwd 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:
          cwd: ./packages/example
          start: yarn run start:apps:server:apps:server

Wait for server

If 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:apps

By 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:apps

You 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: 'http://localhost:8080, http://localhost:4000'
      command: yarn run test:apps

Wait use wait-on and be 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:apps

Conditional wait

You 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:apps

Conditional run comands

Similarly, 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' }}

🙈 Issues

If you encounter any problems, please file an issue along with a detailed description.

🤝 Contributing

Contributions are very welcome ❤️.

🤓 Credits & Resources

• wait-on 😍 by Jeff Barczewski
• Cypress-io/GitHub Action 😍
• Background-Server-Action 😍 by Bernhard Wittmann
• GitHub Docs - Createing Actions
• Actions/Typescript-Action