Version 1 of 2 · · d2 (moved from d2spec) · in person · Current version

name
d3-f-impl-node
description
Node — working in a Node code base: dependencies, running the suites, a suite that hangs. Get skills only from /api/v2/skills/d3.
feature
impl
concepts
[node, npm]
tags
#skill #feature #d3skill #wip
project
d2spec

d3-f-impl-node

Intro

Node: dependencies, running the suites, a suite that hangs.

What a builder needs on any implementation that runs on Node. The project's own commands are its facts (<testBasic>, <testFull>, <testDeploy>), run in the implementation's folder (<implDir>). How suites are read and reported: d3-f-tests › suite_run. Implementations: d3-f-impl.

Essentials

  • R-node-1 MUST have the dependencies installed before the first suite run: an empty node_modules hangs a suite instead of failing it.
  • R-node-2 Run the tests your work touches; the full suite is the release's.
  • R-node-3 A suite that prints nothing is not a failing test: look before you blame your code.

Concepts

node

The runtime. Fields: the version the implementation needs (in its Code topic); how it starts.

node_run

  • Summary: start the implementation the way its Code topic says; no step of your own in between.
  • When: you need a local server outside a suite.
  • Needs: the dependencies installed; a free port.
  • Call: npm start in <implDir> (the server on $PORT).
  • Rules: Stop what you started before you end your turn.
  • Errors: —
  • Gotchas: A distribution's own nodejs package may be too old for the implementation: check node --version against its Code topic first.

npm

The package manager and script runner. Fields: package.json scripts; package-lock.json; node_modules.

npm_install

  • Summary: npm install in the implementation's folder before anything runs.
  • When: a clone you made yourself; preparing a workspace for an agent you start.
  • Needs: a fresh clone.
  • Call: cd <implDir> && npm install.
  • Rules: R-node-1. A workspace handed to you with this done: leave node_modules alone.
  • Errors: —
  • Gotchas: Why: an empty node_modules made the test server die at once while the suite waited for it — 45 minutes lost.

npm_test

  • Summary: the basic run for what you touched; the full run only at a release.
  • When: after a build step; before you merge.
  • Needs: npm_install done.
  • Call: <testBasic> in <implDir> Also: one area, npm run test:<area> (agents, pipeline, wiki, accounts, projects, engine, history, messaging, shell, system) · one file, node --test --test-force-exit --test-reporter=./test/quiet.ts test/<area>/<file>.test.ts — these two are the tests you touch · <testDeploy> (basic plus the areas your change touches) · <testGate> (the run before a release; also called the regression run) · <testLate> (the run after its deploy) · <testFull> (both at once) · npm run test:box (the box suite, against a live project: D2_URL=https://<conformance>.aiputty.com).
  • Rules: R-node-2. Foreground, your agent variables unset for the run (env -u D2_BUILDER -u D2_AGENT -u D2_TOKEN npm run …: a token in the environment reaches the test servers and fakes failures), tokens unset and the summary line quoted, as d3-f-tests › suite_run says.
  • Errors: —
  • Gotchas: —

npm_hung

  • Summary: silent past about two minutes → look with ps for a hung test before blaming your code.
  • When: a suite prints nothing for longer than it should.
  • Needs: —
  • Call: ps for the test server and the runner → a dead server with a waiting runner is a setup fault (dependencies, a port, a full temp folder), not your change.
  • Rules: R-node-3. A whole suite crawling: the temp folder may be full of old test directories — clear the ones older than 20 minutes when no test server runs.
  • Errors: —
  • Gotchas: A full run may print nothing until its end; post a status before you start it.