Run tests against a lane with devlanes with
A Hono API and a Hono page that calls it, with node:test tests in TypeScript that call both over HTTPS. devlanes with --profile e2e -- npm test starts the lane, runs the tests with DEVLANES_PUBLIC_URL_API and DEVLANES_PUBLIC_URL_WEB set, stops the lane and exits with the tests’ code.
Requirements
Section titled “Requirements”- devlanes 0.11.3 or newer, with
devlanes setuprun once - Node 22 or newer with npm
Run it
Section titled “Run it”cd workflows-ci-withdevlanes with --profile e2e --logs-dir devlanes-logs -- npm testexample-ci-with@0 (main): 2/2 readyready api http://127.0.0.1:20570 https://api.example-ci-with.localhostready web http://127.0.0.1:20571 https://example-ci-with.localhost
> test> tsx --test tests/*.test.ts
✔ devlanes with sets the lane's public URLs (0.8353ms)✔ api answers /lane for this lane through the proxy (75.5913ms)✔ web answers /lane for this lane through the proxy (8.6627ms)✔ api runs the e2e profile's start script with NODE_ENV=test (2.941ms)✔ api allows the web origin of this lane (7.8003ms)✔ api sends no CORS header to another origin (2.6371ms)ℹ tests 6ℹ suites 0ℹ pass 6ℹ fail 0ℹ cancelled 0ℹ skipped 0ℹ todo 0ℹ duration_ms 288.3844devlanes with · example-ci-with@0 · exit 0UNIT STATE RUN TIME AVG CPU PEAK CPU AVG MEM PEAK MEMapi ready 2s 0.0% 0.0% 54.2 MiB 54.2 MiBweb ready 2s 3.1% 3.1% 62.5 MiB 62.6 MiBThe exit code is 0. The table at the end appears when the output is not a terminal, as in CI logs. In GitHub Actions devlanes also adds it to the step summary.
To open the page instead, run devlanes start and open https://example-ci-with.localhost. It shows the npm run dev script and the answer the browser fetched from https://api.example-ci-with.localhost.
During a with run
Section titled “During a with run”- The first start of a lane runs the
installtask (npm installat the workspace root), because a new worktree has nonode_modules. - The
e2eprofile is active, so thebuildtask runs too:npm run buildcompiles both apps todist/. A plaindevlanes startskips it. - devlanes starts the services the profile includes (
"*", so both).run_scripts: { dev: start }makesapiandwebrunnpm run start(node dist/index.js) instead ofnpm run dev(tsx watch src/index.ts), and the profile’senvgives bothNODE_ENV=test. - It waits until both
/healthzchecks pass. If a service fails,withprints the failure and exits 1 without running the tests. - It runs
npm testwith the lane’s environment:DEVLANES_PUBLIC_URL_API=https://api.example-ci-with.localhost,DEVLANES_PUBLIC_URL_WEB=https://example-ci-with.localhost,DEVLANES_LANEand the other lane variables, andNODE_EXTRA_CA_CERTSpointing at the devlanes CA, sofetchtrusts the proxy’s certificates. Services do not get theDEVLANES_PUBLIC_URL_*variables.webreads the API’s address fromAPI_URL: ${{ services.api.public_url }}. - It writes each unit’s log to
devlanes-logs/, stops what it started and exits withnpm test’s code.
The tests in tests/lane.test.ts never name a hostname. tests/env.ts reads them from the DEVLANES_PUBLIC_URL_* variables. The tests check that each service’s /lane answers for this lane through the proxy, that the API ran the start script with NODE_ENV=test (npm puts the script name in npm_lifecycle_event), and that the API sends Access-Control-Allow-Origin to the page’s origin and not to https://example.invalid. The API builds that allow-list from DEVLANES_ORIGINS.
A failing run
Section titled “A failing run”Start only api and the web test fails, so with exits 1:
devlanes with --profile e2e api --logs-dir devlanes-logs -- npm testexample-ci-with@0 (main): 1/1 readyready api http://127.0.0.1:20570 https://api.example-ci-with.localhost
> test> tsx --test tests/*.test.ts
✔ devlanes with sets the lane's public URLs (0.8604ms)✔ api answers /lane for this lane through the proxy (54.4561ms)✖ web answers /lane for this lane through the proxy (7.9696ms)✔ api runs the e2e profile's start script with NODE_ENV=test (2.5306ms)✔ api allows the web origin of this lane (6.8869ms)✔ api sends no CORS header to another origin (2.9511ms)ℹ tests 6ℹ suites 0ℹ pass 5ℹ fail 1...✖ web answers /lane for this lane through the proxy (7.9696ms) AssertionError [ERR_ASSERTION]: https://example-ci-with.localhost/lane answered 503...devlanes with · example-ci-with@0 · exit 1UNIT STATE RUN TIME AVG CPU PEAK CPU AVG MEM PEAK MEMapi ready 2s 1.6% 1.6% 54.2 MiB 54.2 MiBDEVLANES_PUBLIC_URL_WEB is still set, because devlanes sets it for every service in devlanes.yaml, and the proxy answers 503 for a service that is not running.
--logs-dir writes one file per unit. The folder is in this example’s .gitignore.
ls devlanes-logscat devlanes-logs/unit-api.logunit-api.logunit-web.log
> start> node dist/index.js
api listening on http://127.0.0.1:20570CORS origins: https://api.example-ci-with.localhost, http://localhost:20570, http://127.0.0.1:20570, https://example-ci-with.localhost, http://localhost:20571, http://127.0.0.1:20571devlanes does not empty the folder first. After the failing run above, unit-api.log was new and unit-web.log was still the one from the run before, so delete the folder between local runs when you read it. A CI job starts from a clean checkout.
GitHub Actions
Section titled “GitHub Actions”github-workflow.yml is a workflow to copy into .github/workflows/. The examples repository’s own CI does not run it, and it has not been run for this example. It checks out the repository, sets up Node 24 and runs devlanes-run/action@v0 with command: with, profile: e2e and run: npm test. working-directory: workflows-ci-with points the action at this folder’s devlanes.yaml; use . when the file is at the repository root. The step fails when the tests fail, and the action then uploads the unit logs, the daemon’s log and the output of devlanes doctor as an artifact. On Linux runners the action trusts the devlanes CA and lets the proxy use port 443, so the URLs match the ones above.
Ad-hoc checks with exec
Section titled “Ad-hoc checks with exec”Against a lane that is already running, an agent or a script runs a one-off command as a unit of the lane with devlanes exec. The command gets the DEVLANES_PUBLIC_URL_* variables, and devlanes logs and devlanes status show its output and state:
devlanes start --no-uidevlanes wait web --timeout 2mdevlanes exec --name smoke -- node --use-system-ca --import tsx tests/smoke.tsA few seconds later, devlanes logs smoke prints:
smoke#1 api https://api.example-ci-with.localhost/healthz 200 oksmoke#2 web https://example-ci-with.localhost/healthz 200 okand devlanes status lists smoke next to the services and tasks:
example-ci-with LANE BRANCH STATE SERVICES CPU MEM URL 0 main running 2/2 0.0% 165.2 MiB https://example-ci-with.localhost
UNIT STATE PORT CPU MEM URL api ready 20570 0.0% 79.9 MiB https://api.example-ci-with.localhost web ready 20571 0.0% 85.3 MiB https://example-ci-with.localhost build exited – – – install exited – – – smoke exited – – –In devlanes 0.11.3, exec units do not get NODE_EXTRA_CA_CERTS, so the same command without --use-system-ca fails with self-signed certificate in certificate chain and smoke shows as failed. --use-system-ca makes Node read the CA that devlanes setup added to the system store, and --import tsx runs the TypeScript file. devlanes wait smoke reports a failed exec unit with its log tail and exits 1, but counts a running one as ready, so read the result from devlanes status or devlanes logs.
Try next
Section titled “Try next”Run
withwhiledevlanes starthas the lane running.withkeeps the runningdevunits and starts nothing, so the profile check fails and the lane stays up:example-ci-with@0 (main): 2/2 ready, already running (nothing started)...✖ api runs the e2e profile's start script with NODE_ENV=test (2.2683ms)The assertion reads
'dev' !== 'start'. Rundevlanes stopfirst.Run the tests in a second worktree:
git worktree add ../examples-checkout -b feat/checkout, thencd ../examples-checkout/workflows-ci-with && devlanes with --profile e2e -- npm test. The worktree is a lane of its own.Without a worktree, run the tests against a second lane in this folder:
Terminal window devlanes lane new --name example-ci-with-review --startdevlanes stop --lane example-ci-with-reviewdevlanes with --lane example-ci-with-review --profile e2e -- npm testThe same tests pass against https://api.example-ci-with1.localhost and https://example-ci-with1.localhost, and the run ends with
devlanes with · example-ci-with@1 · exit 0.Remove the lanes with
devlanes lane clean example-ci-with-review --yesanddevlanes lane clean 0 --yes.
devlanes.yaml:apiandwebwith their hostnames and/healthzchecks, theinstallandbuildtasks, and thee2eprofile withrun_scriptsandNODE_ENV.tests/lane.test.ts: thenode:testtestsnpm testruns through tsx.tests/smoke.ts: the/healthzcheck fordevlanes exec.github-workflow.yml: the GitHub Actions workflow ondevlanes-run/action.apps/api/src/app.ts: the API’s routes (/,/api/items,/lane,/healthz) and CORS fromDEVLANES_ORIGINS.apps/*/package.json: thedevandstartscripts.