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:
mkdir shout
cd shout
git init -b main
npm init -y
mkdir src testcat > 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)
})
JSPoint 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:
npm pkg set scripts.test="node --test"
npm install --package-lock-only
ls package-lock.jsonCheck it worked
npm testThe 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:
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 testThe 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:
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
YAMLWhat the new parts do:
actions/setup-node@v7installs the Node.js version you ask for.cache: npmsaves npm's download cache between runs, keyed onpackage-lock.json, sonpm cifetches 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-versiontakes each value in the list in turn. GitHub creates two jobs,test (24)andtest (26), and runs them in parallel.fail-fast: falselets the second one finish if the first fails, so you see whether a failure is specific to one version.concurrencywithcancel-in-progress: truecancels 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 ciinstead ofnpm install: it deletesnode_modules, installs from the lock file only, and fails ifpackage.jsonand the lock file disagree. That is the repeatable behaviour a pipeline needs.permissions: contents: readgives 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:
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:
printf 'node_modules\n' > .gitignore
git add .
git commit -m "Add shout function, tests and CI workflow"git remote add origin git@github.com:YOUR-USER/YOUR-REPO.git
git push -u origin mainOpen 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 cifails withThe npm ci command can only install with an existing package-lock.json: the lock file is not committed. Rungit add package-lock.json, commit and push.Dependencies lock file is not foundfrom setup-node:cache: npmneeds apackage-lock.json(ornpm-shrinkwrap.json) at the repository root. If your project is in a subfolder, addcache-dependency-path: subfolder/package-lock.jsonunderwith:.- The tests pass locally and fail in the workflow: compare Node.js versions first (
node -vagainst 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 andtest (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.
Get new tutorials