Tests & doc comments

Tests

test "name" => expr at the top level defines a test: expr must be a bool. It is stored as an ordinary term named test_<slug> (lowercase, runs of other characters become _) that hashes exactly like the plain let, so a test is shared, synced and brought in like any other definition. Only the unhashed source text records that it is a test.

let double = (n: int): int => n * 2

/** Doubles a number, twice. Shown on hover and in search. */
let twice = (n: int): int => double(double(n))

test "double doubles" => double(4) == 8
test "twice quadruples" => twice(3) == 12

clay test [file|name] [--no-ucm] [--json] prints PASS, FAIL or ERROR per test and exits non-zero on any failure. Each test runs in the in-process engine and again through UCM, and a difference between the two is reported as a disagreement. In the editor, Run prints PASS or FAIL for each test in the buffer, offline too.

Doc comments

/** ... */ immediately before a definition is its documentation. It is a grammar extra kept in the definition’s unhashed source text, so it can never change a hash, and it survives rename, update, move, sync and the bucket. It shows in editor hover, in the tooltip of the definition’s chip in the This-file panel, in Browser search results (searchable) and in clay view.

Only /** */ counts (no ///). The doc is read from the very start of a definition’s text, after blank lines and // lines.