Skip to content
IdentityFlow

Run the starter's tests in CI

Install locked dependencies Check types workflows and tests Workflow Tests real PostgreSQL then then
Install locked dependencies Check types workflows and tests Workflow Tests real PostgreSQL then then
A fresh checkout installs dependencies, checks types and runs Workflow Tests, with a separate result for each check.

On this page you run the starter’s checks in a CI job: the same npm ci, npm run check and npm run test:workflow you ran locally, on a fresh checkout. CI for workflow projects describes the job for any workflow project; this page is the starter’s version of it.

Use a runner with Node.js 26.8.1, Docker and the release’s Workflow Test distribution. The result is three passing checks with separate logs, not a deployment. First make the distribution available, then add the job below. Runner requirements lists the platform details.

The job

Section titled “The job”

The starter’s .gitignore excludes bin/, so a fresh checkout has no Workflow Test distribution. The job copies it to bin/identity-flow-test/, where npm run test:workflow looks for it. IDENTITY_FLOW_TEST_DIR is the unpacked distribution folder, the one that contains the identity-flow-test executable. Run the commands from the starter’s root folder and make each one its own step in your CI definition:

#!/usr/bin/env bash
# CI job for the starter, run from the starter's root folder.
# IDENTITY_FLOW_TEST_DIR is the unpacked Workflow Test distribution, for example
# /opt/identity-flow-test-v0.3.1-linux-x64.
set -euo pipefail
mkdir -p ci-output


# bin/ is not in version control. Put the Workflow Test distribution where
# `npm run test:workflow` looks for it: bin/identity-flow-test/identity-flow-test.
mkdir -p bin
cp -R "$IDENTITY_FLOW_TEST_DIR" bin/identity-flow-test


# Install exactly the package versions package-lock.json records.
npm ci 2>&1 | tee ci-output/install.log


# Type-check workflows, hooks and tests.
npm run check 2>&1 | tee ci-output/typecheck.log


# Run the Workflow Tests. Each run starts and removes its own PostgreSQL
# container, so the runner needs Docker.
npm run test:workflow 2>&1 | tee ci-output/workflow-tests.log
  • npm run check runs tsc --noEmit. It shows that the code compiles, not that a workflow ran.
  • npm run test:workflow first checks that the distribution reports version 0.3.1 and prints workshop: identity-flow-test 0.3.1 (<commit>), then runs every test vitest.config.ts selects. If the distribution is missing, it stops with IFLOW_DISTRIBUTION_MISSING.
  • npm run check:exercises type-checks the practice tasks as well. Add it if your project keeps them.

Keep the type check and the tests as separate steps, so each reports its own status. A passing type check next to a failed test run is easy to misread as a pass.

Runner platform and distribution requirements

What the runner needs

Section titled “What the runner needs”
  • Node.js 26.8.1 with npm. The starter’s .npmrc sets engine-strict=true, so npm ci refuses a Node.js older than the version in package.json. The packages come from the public npm registry.
  • The Workflow Test distribution for the runner’s platform, usually identity-flow-test-v0.3.1-linux-x64, unpacked somewhere the job can read it. It brings its own Node.js and needs a glibc-based Linux; Alpine and other musl-based images cannot run it. It is delivered with the release, not through npm, so store it where your runners can fetch it, such as an internal artifact store or the runner image.
  • Docker. Each test run starts its own PostgreSQL container and removes it at the end.

The job does not start IdentityFlow, so it does not need the IdentityFlow program or the starter’s containers.

Project release

Section titled “Project release”

A tested version of your starter project is its commit together with its package-lock.json and the IdentityFlow version its tests ran with, which is the line workshop: identity-flow-test 0.3.1 (<commit>) in ci-output/workflow-tests.log. Keep those with the logs; What to archive lists the rest. Nothing is published to a registry.

A green job deploys nothing. To run the project on a server, follow Install and run IdentityFlow. Install the project there with npm ci, the same way as in CI: the program compiles every Workflow Definition together with the packages it imports, and a different install can change that bundle and stop the start with WF_DEFINITION_BUNDLE_CHANGED.