Reference

Test API

Everything @wellactually/sdk/v4/test exports, for the *.test.ts files of a principle. test, describe and expect come from vitest.

import { describe, expect, test } from "vitest";
import { command, deleted, detect, edit, output, prompt, read, source, write } from "@wellactually/sdk/v4/test";

detect(event, options?)#

detect(event, options?: { project?: string }): Finding[]

Runs the real detector of the principle the test file is in, on one event, the way a session does: whether a handler wants it first, then the isolate with its limits. It returns the findings as the agent would get them.

It throws when the detector throws, runs out of time or memory, reports a line the file does not have, or a match that is not in the event.

project is a folder of the principle, such as "fixtures/flutter_app", that becomes the project the event happens in. The detector can read its files with node:fs. Without it the only file that exists is the file of the event.

Events#

Function	Builds
`write(path, content, { isNew? })`	A file the agent wrote in full. Every line counts as written.
`edit(path, content, { written?, removed?, before? })`	A file the agent changed. `content` is the file after the edit, `written` the text it put in and `removed` the text it took out, each as one string or a list. `before` is the file as it was, which gives each removed line its number.
`read(path, content)`	A file the agent read.
`deleted(path, content)`	A file the agent deleted, with what it held. Every line counts as removed.
`prompt(text)`	A message, or a brief for a subagent.
`command(text)`	A shell command about to run.
`output(command, text)`	What `command` printed.

path is relative to a made-up project root, /project, which is also the cwd of prompts, commands and outputs. edit throws when written does not occur in content, or removed does not occur in before.

const before = "void main() {\n  test('loads', () {});\n  test('saves', () {});\n}";
const after = "void main() {\n  test('loads', () {});\n}";
expect(detect(edit("test/store_test.dart", after, { removed: "  test('saves', () {});", before }))).toEqual([{ line: 3, removed: true }]);
expect(detect(deleted("test/store_test.dart", before))).toEqual([{}]);

source#

source`...`: string

A template string without the indentation of the test around it, and without its first and last line when they are empty. ${ and a backtick inside it need a backslash.

What runs in the registry#

The registry runs the same files again inside the isolate, with a small copy of vitest:

Kind	Available
Tests	`test`, `it`, `describe`, `test.each`
Matchers	`toEqual`, `toStrictEqual`, `toBe`, `toHaveLength`, `toContain`, `toContainEqual`, `toMatchObject`, `toBeTruthy`, `toBeFalsy`, `toBeNull`, `toBeUndefined`, `toBeDefined`, `toThrow`
Modifiers	`.not`

Tests are not async. Anything else passes on your machine and fails on the registry, with a message that names it.