Skip to main content

CI/CD and automation · Intermediate · 13 min

How to Run Node.js Tests Automatically with GitHub Actions

By Padding · Updated 15 Nov 2026
GitHub Actions · Node.js 26

You will write tests with Node.js's built-in test runner, run them on every push and pull request with a GitHub Actions workflow that caches npm downloads and tries two Node.js versions, and check the workflow file locally before you push it.

On this page

Tests that nobody runs protect nothing. The usual fix is to make the computer run them: on every push and every pull request, in a clean environment that does not depend on what happens to be installed on your laptop. If the tests fail, the pull request shows a red cross before anyone merges it.

In this tutorial you will create a small Node.js project with tests, confirm they pass on your own machine, and then wrap the same two commands in a GitHub Actions workflow. It builds on /tutorials/github-actions-first-workflow, which explains the workflow file's basic shape.

Step 1 · Create a project with a test

Node.js ships a test runner, node:test, so you need no framework to start. Make a project with one function and its tests:

Bash
mkdir shout
cd shout
git init -b main
npm init -y
mkdir src test
Bash
cat > src/shout.js <<'JS'
function shout(text) {
  if (typeof text !== 'string') {
    throw new TypeError('shout needs a string')
  }
  return text.trim().toUpperCase() + '!'
}

module.exports = { shout }
JS

cat > test/shout.test.js <<'JS'
const test = require('node:test')
const assert = require('node:assert/strict')
const { shout } = require('../src/shout.js')

test('upper-cases and adds an exclamation mark', () => {
  assert.equal(shout('hello'), 'HELLO!')
})

test('trims spaces first', () => {
  assert.equal(shout('  hi  '), 'HI!')
})

test('rejects anything that is not a string', () => {
  assert.throws(() => shout(42), TypeError)
})
JS

Point the test script in package.json at the runner. npm pkg set edits the file for you. Then generate a lock file. The workflow will use npm ci, which needs package-lock.json and installs exactly what it lists:

Bash
npm pkg set scripts.test="node --test"
npm install --package-lock-only
ls package-lock.json

Check it worked

Bash
npm test

The runner prints each test with a tick and ends with a summary of tests 3, pass 3 and fail 0. Break one on purpose to see what a failure looks like, then undo it:

Bash
sed -i.bak "s/'HELLO!'/'HELLO?'/" test/shout.test.js && rm test/shout.test.js.bak
npm test || echo "tests failed, as expected (exit code $?)"
sed -i.bak "s/'HELLO?'/'HELLO!'/" test/shout.test.js && rm test/shout.test.js.bak
npm test

The failing run shows the expected and actual values, and npm test exits with a non-zero code. That exit code is what a workflow uses to decide pass or fail. Any command that exits non-zero fails the step, and a failed step fails the job.

Step 2 · Write the workflow

Create .github/workflows/test.yml. It runs npm ci and npm test on two Node.js versions: 24 and 26, both long-term-support lines when this was written. Check nodejs.org/en/about/previous-releases for the current schedule and change the list when a line leaves support. A matrix repeats a job once per value:

Bash
mkdir -p .github/workflows
cat > .github/workflows/test.yml <<'YAML'
name: Test

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: test-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node-version: [24, 26]
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - run: npm ci
      - run: npm test
YAML

What the new parts do:

  • actions/setup-node@v7 installs the Node.js version you ask for. cache: npm saves npm's download cache between runs, keyed on package-lock.json, so npm ci fetches less each time. Both actions are at their current major version, v7, as of this writing; their release pages are github.com/actions/checkout/releases and github.com/actions/setup-node/releases.
  • matrix.node-version takes each value in the list in turn. GitHub creates two jobs, test (24) and test (26), and runs them in parallel. fail-fast: false lets the second one finish if the first fails, so you see whether a failure is specific to one version.
  • concurrency with cancel-in-progress: true cancels an older run of the same branch when you push again. You do not wait for tests of code that is already out of date.
  • npm ci instead of npm install: it deletes node_modules, installs from the lock file only, and fails if package.json and the lock file disagree. That is the repeatable behaviour a pipeline needs.
  • permissions: contents: read gives the run's token read-only access. Nothing here needs more.

Check it worked

Check the workflow file on your computer. actionlint is a checker for workflow files, from github.com/rhysd/actionlint. Download a release for your system (version 1.7.12 here), as shown in /tutorials/github-actions-first-workflow, then run it in the repository:

Bash
actionlint
echo "actionlint exit code: $?"

No output and exit code 0 mean it found nothing wrong. It also checks the run scripts and the expressions such as ${{ matrix.node-version }}.

Step 3 · Push and read the result

Commit the project. The .gitignore keeps node_modules out of the repository. Then push to a GitHub repository you own:

Bash
printf 'node_modules\n' > .gitignore
git add .
git commit -m "Add shout function, tests and CI workflow"
Bash
git remote add origin git@github.com:YOUR-USER/YOUR-REPO.git
git push -u origin main

Open the repository's Actions tab. The workflow Test shows a run with two jobs, test (24) and test (26). Open one to see the steps: checkout, setup Node, npm ci, npm test. The test output is the same as on your computer. On the second run, the setup-node step reports a cache hit in its log, and npm ci is faster. With the GitHub CLI, gh run list and gh run watch show the same in the terminal.

Troubleshooting

  • npm ci fails with The npm ci command can only install with an existing package-lock.json: the lock file is not committed. Run git add package-lock.json, commit and push.
  • Dependencies lock file is not found from setup-node: cache: npm needs a package-lock.json (or npm-shrinkwrap.json) at the repository root. If your project is in a subfolder, add cache-dependency-path: subfolder/package-lock.json under with:.
  • The tests pass locally and fail in the workflow: compare Node.js versions first (node -v against the matrix). Then look for files that exist only on your machine, such as a .env. A pipeline starts from a clean checkout of what is committed.
  • A job named test (24) fails and test (26) passes: your code or a dependency behaves differently on that Node.js version. The matrix did its job.

Step 4 · Make the check count

A red cross is only advice until merging requires a green one. In the repository settings, look for something like Branches or Rules, create a rule for main, and require the status checks test (24) and test (26) to pass before merging a pull request. The check names appear in the rule's search box only after they have run once. Labels in the settings pages change from time to time, so follow GitHub's current guide: docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches.

If your tests need credentials, such as an API key for a staging service, do not put them in test.yml or in the repository. Add them as repository secrets in the settings and read them in a step with env: API_KEY: ${{ secrets.API_KEY }}. Secrets are not passed to workflows triggered by pull requests from forks, so tests that need them will not run there.

Next steps

  • Deploy after the tests pass: /tutorials/deploy-to-a-server-over-ssh-with-github-actions.
  • Keep tokens and keys out of your repository: /tutorials/keep-secrets-out-of-git.
  • Related reference pages: docs.github.com/en/actions/use-cases-and-examples/building-and-testing/building-and-testing-nodejs and nodejs.org/api/test.html.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.