Tests on Every Push with GitHub Actions

A GitHub Actions workflow in .github/workflows/ci.yml runs npm ci, the linter, the format check and the tests on a fresh computer at every push and pull request, so a broken change shows up as a red cross on its commit, with a log that says which step failed and why.

Journeyman · Node.js · GitHub Actions · Software Development · Updated

By

After this lesson you can

  • Write a GitHub Actions workflow that checks out the code, sets up Node and runs npm ci, the linter, the format check and the tests on every push
  • Read a failed workflow run to find the step and the problem, fix it on your computer, and push again until the run passes

Key takeaways

  • Continuous integration runs the project's checks on every change, on a fresh computer, so problems are caught before they're merged rather than after.
  • A workflow is a YAML file in .github/workflows. Its on line says when it runs, runs-on picks the computer, and its steps run one after another.
  • The steps for a Node project are actions/checkout, actions/setup-node with the Node version and the npm cache, then npm ci, the linter, the format check and npm test.
  • A step fails when its command ends with an exit code other than 0, and the steps after it don't run. The failed step's log shows the same output you'd see on your own computer.
  • A status badge in the README shows whether the latest run passed, to anyone who opens the repository.

Open almost any team's repository on GitHub and you'll see a small green check or a red cross beside each commit. That's continuous integration at work, the "CI" in the "CI/CD" that job listings ask for. On a team, nobody merges a change until its check is green; on your own projects, it catches the day you forgot to run the tests.

The Lost and Found Desk's three students each run npm run lint and npm test before they push. Usually. Last week Luis forgot, and a broken route sat on GitHub for two days before anyone noticed.

A health inspection on every delivery

Imagine a kitchen's health inspection that happened every time a delivery arrived: an inspector checks each crate at the door, the same way every time, and turns away a bad one before it reaches the shelves. Nobody has to remember to call them.

Continuous integration, or CI, is that inspector for code. Every push is a delivery, and the same checks run on it every time, on a fresh computer that has only what's in the repository. GitHub Actions is the CI service built into GitHub, free for public repositories. You describe the checks in a workflow file, and GitHub runs it on a runner, a computer it starts for each run and throws away afterwards.

A push travels from a laptop to GitHub, where a runner checks the code step by step (checkout, setup-node, npm ci, lint, format check, test) and puts a green check on the commit when every step passes, or a red cross on the step that failed

The workflow file

A workflow lives in the folder .github/workflows/ at the top of the repository, in a file such as ci.yml. It's written in YAML (read "YAM-ul"), a format for settings: each line is name: value, indentation with spaces shows what belongs inside what, and a line starting with - (read "dash") is one item of a list.

name: CI

on: [push, pull_request]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 26
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run format:check
      - run: npm test

Top to bottom:

  • name: CI is what the Actions tab calls the workflow.
  • on: [push, pull_request] says when it runs: on every push, and on every pull request (a request to merge a branch, which the team reviews).
  • jobs holds the work. This one has a single job, lint-and-test, and runs-on: ubuntu-latest asks for a fresh Linux runner. Node behaves the same there as on Windows or a Mac.
  • steps run in order. A step either uses an action someone else wrote, or **run**s a command. actions/checkout@v7 copies the repository onto the runner; @v7 (read "at v seven") pins its version, as --save-exact pins a package's. actions/setup-node@v7 installs Node, and with gives it two settings: Node 26, and cache: npm, which keeps npm's downloads between runs, keyed by package-lock.json, so later runs install faster.
  • npm ci installs exactly what package-lock.json records, as Package Versions, npm ci and npm audit explained. Then come the three checks, cheapest first.

Tests that use mongodb-memory-server run here too: the runner downloads MongoDB on its first run, as your computer did.

Run the steps on your computer first

Every push to try a fix costs a minute or two, so run the same commands in VS Code's terminal before you push:

npm ci
npm run lint
npm run format:check
npm test

The end of the run, from npm test:

✔ GET /items answers 200 with all 3 items (22.5634ms)
✔ GET /items/2 answers 200 with the math textbook (6.3816ms)
✔ GET /items/99 answers 404 (3.4487ms)
ℹ tests 3
ℹ suites 0
ℹ pass 3
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 221.6004

npm run lint and npm run format:check printed no problems, so all four steps would pass on GitHub too. Commit .github/workflows/ci.yml with the rest of your work and push.

Reading a run, red and green

After the push, open the repository on GitHub and choose the Actions tab. Your run is listed under CI with your commit's message; a yellow dot means it's still running. Choose it, then the job lint-and-test, and you see every step with a check mark, plus a few GitHub adds itself, such as Set up job and Complete job.

GitHub's Actions tab showing a finished run of the CI workflow: the job lint-and-test with a green check beside every step, from checkout to npm test

Now Mei adds a status filter to GET /items with req.query.status == undefined, and pushes without linting. A step fails when its command ends with an exit code other than 0 (Arguments, Exit Codes and Clear Errors showed exit codes), and ESLint exits with 1 when it finds a problem. So the run stops at npm run lint with a red cross, the steps after it don't run, a red cross appears beside the commit, and GitHub emails Mei. Choose the failed step to open its log. It holds what npm run lint printed on the runner, the same as on her computer, with the runner's folder in the file's path. The lines that matter:

  7:24  error  Expected '===' and instead saw '=='  eqeqeq

✖ 1 problem (1 error, 0 warnings)

The log ends with GitHub's own line saying the process completed with exit code 1. To fix a failed run, read the log, change the code on your computer, run the same command there until it passes, then commit and push. The new push starts a new run, and the check turns green. A run that fails only on GitHub usually means something exists on your computer and not in the repository, such as a file you never committed.

A status badge

A badge in the README shows the latest run's result to everyone who opens the repository. Add this line at the top of README.md, with your GitHub name and repository in the address:

![CI](https://github.com/your-name/lost-and-found-api/actions/workflows/ci.yml/badge.svg)

It shows CI passing in green, or CI failing in red, and changes by itself with every run.

Check yourself

2 questions to try on the lesson page.

So what

With CI, "it works on my computer" stops being the end of the story: every push is checked the same way on a fresh computer, so you and your team find out within minutes, not days, when something breaks.

Key terms

Related