ai:skills › d3-f-tests · version 1 ·
HistoryMarkdown
name
d3-f-tests
description
Tests — design tests and code tests, test lines per behaviour code and their status, UI tests as the person, running suites, test data, stories on small projects, and the tests watch. Get skills only from /api/v2/skills/d3.
feature
tests
concepts
[test, testLine, suite, testData, story, check]
tags
#skill #feature #d3skill #wip

d3-f-tests✎ edit

Intro✎ edit

Design tests and code tests, one line per behaviour.

Every behaviour a project promises (a spec line with a code) has at least one test. Design tests are black-box, written from the Spec and Design before the work is ticketed, and are the contract; code tests belong to whoever builds. The tests topic keeps one line per case with its status, so anyone can see what is proven. Behaviour codes and doc layers: d3-f-design. Which suites exist and how they are run on a given code base: its implementation skills and the project's facts.

Essentials✎ edit

  • R-tests-1 MUST give every spec line with a code at least one test line, written before its ticket is filed.
  • R-tests-2 NEVER change what a design test checks to make it pass: one that can't pass as written goes back as a design call.
  • R-tests-3 MUST start a test's name with its code (WAITLIST-1 a full event…); code that realises a behaviour carries // covers: waitlist-1.
  • R-tests-4 MUST run UI tests as the person the case is about, in a person's session — NEVER with an AI or ops token, which take other branches.
  • R-tests-5 Every failure is real: there is no list of expected failures; a collected count that falls is a fault, not a pass.
  • R-tests-6 Tested names the test file or commit that proves it.
  • R-tests-7 Quote a suite's summary line, NEVER pages of output.

Concepts✎ edit

test✎ edit

One automated check. Also called: a case, a check. Kinds: design test — black-box (routes, statuses, error codes, what a person sees; never function names or files), with its own code (BUSX-1), written by the design's author, run unchanged on every build; code test — the builder's own; layout and wording test — exact markup, classes, wording and order of a designed page, kept with the code and owned by the design's author (change its expected markup, never what it proves); behaviour test — routes, permissions, data, data-* attributes, the builder's.

test_write✎ edit

  • Summary: black-box, one line per case under the feature's {#id}, written before the ticket that names them.
  • When: a spec line is added or changed — in the same change.
  • Needs: the feature's {#id} and behaviour codes (d3-f-design › code).
  • Call: a line in the tests topic's draft (d3-f-drafts › draft_save): code, name, the steps as the person or caller, the expected answer, then the codes it covers, ending [[Spec#^<code>]].
  • Rules: R-tests-1, R-tests-3. More than one line where a behaviour's cases need them. A requirement or test id is never reused; a dropped one is struck through, not deleted.
  • Errors: —
  • Gotchas: —

test_cantPass✎ edit

  • Summary: a design test that can't pass as written is a design call, never an edit.
  • When: building, and a design test fails for a reason the code can't fix.
  • Needs: the test's code and what it expects vs what is possible.
  • Call: d3-f-pipeline › item_ask on the item you hold.
  • Rules: R-tests-2.
  • Errors: —
  • Gotchas: —

test_fail✎ edit

  • Summary: a failing test becomes an item for whoever builds, with the failing code and how to see it.
  • When: a run of the design tests fails on built work.
  • Needs: the test's code, the steps, what came back.
  • Call: d3-f-pipeline › item_file for the builders' lane.
  • Rules: The one who finds it doesn't fix the code, and doesn't change the test.
  • Errors: —
  • Gotchas: —

testLine✎ edit

One case's line in the tests topic. Also called: a test row. States: Planned / not built → gap (built, not tested yet, with why) → Tested (naming the test file or commit).

testLine_status✎ edit

  • Summary: keep each line's status true; Tested names the file or commit.
  • When: a behaviour is built, tested, or found untested.
  • Needs: the test file or commit.
  • Call: the tests topic's draft (d3-f-drafts › draft_save).
  • Rules: R-tests-6. The design's test lines are kept by the design's author; the code base's own test topic by its builders, from the builder's As built note.
  • Errors: —
  • Gotchas: —

suite✎ edit

A named set of tests run together. Also called: the tests, a run. Kinds (names per code base): basic (a quick regression), component (what a change touched), full (everything), box (against a deployed project after a release), visible (a real browser looks at the pages after a release: VIS-1).

suite_run✎ edit

  • Summary: run in the foreground, with your agent tokens unset; read the totals; quote the summary line.
  • When: after building (the tests for what you touched); the full suite only at a release.
  • Needs: dependencies installed; your agent environment unset.
  • Call: the code base's own commands (its implementation skill) — e.g. env -u <agent vars> <run command>.
  • Rules: R-tests-5, R-tests-7. A failing todo counts as a todo. A test server takes the port the OS gives it (PORT=0), never one from a range. Building means the component tests for what you touched, not the full suite (d3-f-git › merge_toWork). A full run is timed every time, and its minutes are reported with its summary line.
  • Errors: a dozen unexplained failures in unrelated areas → your agent tokens are exported into the test servers: unset them · a test hitting another test's server → a port drawn from a range: use PORT=0.
  • Gotchas: an empty dependency folder makes a suite hang instead of failing — install first. A suite that prints nothing until the end and has no per-test timeout: silent well past its usual time → look for a hung test process; a crawling suite can mean stale test folders left in the temp directory. Run it in the foreground and wait — a backgrounded suite dies with your turn.

testData✎ edit

What tests create. Rules of the house: test data lives in one folder of its own that nothing else writes to, so it can be pruned whole; realms and projects reserved for tests are made only locally — tests against a live box never create accounts or projects, only t- topics and objects; suites that need a database of their own skip themselves without its setting, so a builder never needs one.

story✎ edit

On small projects (hero, creator), a Story: topic per feature (feature: <id> in its frontmatter) is the feature's test. Also called: a check, "does it still work".

story_check✎ edit

  • Summary: run the feature's story after a change; its last run makes the feature checked or fails.
  • When: after changing anything a feature is made of.
  • Needs: the Story: topic with the feature's id.
  • Call: d3-f-engine › story_run.
  • Rules: A story naming an id the Specification lacks shows under Not described yet (d3-f-design › spec_small).
  • Errors: —
  • Gotchas: —

check✎ edit

A watch's check on this feature (d3-f-guard-reports › watch).

check_tests✎ edit

  • Summary: the tests watch: eight checks of the test topics against Spec and Design.
  • When: daily and after each checkpoint.
  • Needs: topics tagged d2-test, Spec, SpecUi, Design, their histories.
  • Call: published reads (d3-f-guard-reports › report_read):
    1. Coverage: every ^x-n in Spec and SpecUi has a test line, and once built a test citing it; report missing ones, newest first.
    2. Dangling: every code, section or anchor a test cites exists.
    3. Drift: a spec line changed (topic history) after the test that cites it — quote both.
    4. Truthful status: Tested names a file or commit; a design test still not run on a feature marked built.
    5. Design tests untouched: wording changed by anyone but the design's author.
    6. Creep: a test checking behaviour no spec line asks for.
    7. Uncoded items: Spec and SpecUi bullets without a code, per section (built sections first).
    8. UI as the person: a page test rendered with an AI or ops token instead of a person's session.
  • Rules: Owners: 1–3, 5, 6 → the designers' lane; 4 → the builders' lane (unproven Tested) or the designers' (not run). Summary line: tests: N findings; uncoded: Spec a of b, UiSpec c.
  • Errors: —
  • Gotchas: —

check_untested✎ edit

  • Summary: a standing line in every watcher report — the count of codes nothing tests, new ones first; never a finding.
  • When: every watcher run.
  • Needs: your last run's list.
  • Call: GET /api/v2/codes?untested=1 → the count, then the codes not on your last list first, each linked to its line (/features?feature=<feature>#c-<code>) with its section.
  • Rules: No item is filed for it.
  • Errors: —
  • Gotchas: Why: a suite only fails on what it checks, so a behaviour nothing checks breaks in silence — a spec line with no test line and no test broke unnoticed until a person opened the page.

Rules✎ edit

  • R-tests-9 Every release: can one see the home page? After each deploy a real browser opens the home page logged out and a project page as a person, on a phone (390 px) and a desktop (1280 px), light and dark: page loads, no page errors, nothing covers it, a screenshot each (VIS-1). A failure fails the release's gate. Why: 0.263.0 shipped a closed chat box that covered every page on phones (black in dark mode); every suite passed, because none looked at a page in a browser.
  • R-tests-8 The catalog: a code base lists every test by file with its coverage by code, and that listing is pasted into its own test topic after each release that changes tests.

Errors✎ edit

  • a dozen unexplained failures in unrelated areas — agent tokens exported into the test servers → unset them. see #suite_run
  • a test hitting another test's server — a port drawn from a range → PORT=0. see #suite_run
  • a design test that can't pass as written — don't edit it → a design call. see #test_cantPass
  • a suite silent far past its usual time — a hung test or an empty dependency folder. see #suite_run