runningBuild( ) → string

Which build this engine is, in the same words. `engine.platform` is the binary's own answer — deposited at its entry point, where the binary is the only thing that knows — so a suite asking which build it runs on and a gate reading the result are answering off one fact. An engine that names no build answers `unknown`, which is in no hold's set, so every scoped hold lifts and the cases gate: a build nobody can identify reports its failures rather than hiding them.

buildsClause(on: { string }?) → string

How a report names the builds a hold stands on, as a clause to follow the issue: a hold naming none stands on every build and says nothing extra, and one naming builds says which, so a reader of either report can tell a hold that gates nowhere from one that gates everywhere but here.

nextSceneCounter( ) → void

duplicateSceneFixture(fixture: string, destFolder: string, label: string) → any

Internal: copy a `.scene` fixture folder to `destFolder` and resolve the duplicate to an `AssetRef<scene>`. A `.scene` asset is scene.json + entrypoint.luau; each file is read by known name and re-written at the destination, so the engine mints fresh meta and two duplicates of the same fixture carry distinct asset identities. `label` names the caller in the raised message. Shared by `Test.useScene` and `Test.ensureRootLayer`.

activeRootWithPath( ) → any

Internal: the active root layer when it can answer for a scene — a proxy carrying a non-empty path. `layers.active` reads non-nil for a layer the engine is still loading or unloading too, and that proxy reports an empty path; a scene-scoped surface reaches through the path, so it is what decides whether a root is there to be used.

modeFlipInFlight( ) → boolean

Internal: whether an edit↔play flip's transition is materialising the layer set right now. The transition unloads the root layer and loads it again, and the load publishes a FRESH proxy for it: the proxy a caller took beforehand stops being the live scene the moment the unload lands, so reads through it answer for a scene that is gone and live writes through it reach nothing. A helper that hands a body a scene waits this out first.

sceneRebuildInFlight( ) → boolean

Internal: whether the engine is rebuilding the live scene right now — a flip's transition is materialising the layer set, or the loader is carrying a load. The layers module owns both signals and publishes them as one predicate.

releaseLoadedLayer(ref: any) → boolean

Internal: unload a layer this harness loaded and hold until the engine has released it. Answers whether the layer left the engine's loaded set. The unload goes through the live proxy the engine's own loaded set carries for the guid. A ref-keyed unload resolves the layer through `layers.find`, which reads a slot as gone from the moment an unload is issued against it until the next load announces itself — so a layer a flip's transition is carrying, or one that has been through a load / replace cycle, resolves to nothing and the unload reaches nothing at all. The loaded set is the engine's own answer for what is loaded, so it is what both the unload and the wait read. A flip's transition is one of those windows and the runner opens it right before the cleanups run: it unloads the root and loads it again over the frames that follow, and an unload issued into it is the no-op above. So the transition lands first. A caller that then drops the folder the layer reads from acts on the answer: a folder taken from under a live layer leaves that layer holding a scene the engine can no longer read, and every later reach through `layers.active` — a reload, a save, a mode flip — answers for it, in this test and in every test after it.

unloadStandInLayer( ) → void

Internal: unload the stand-in root layer, leaving its source folder for the next test that asks for a root. The caller's next read of `layers.active` sees the release land.

registerAutoTeardown(fn: ?) → void

Internal: push a no-arg function onto the current test's auto-teardown list. Drained (LIFO) by Test.run() after suite.afterEach, on success AND failure paths, so cleanup fires even when the test body errors out.

slugForResultPath(s: ?) → void

Internal: sanitize a name into a filesystem-safe slug. Lowercase alnum + dash; anything else collapses to dash. Used for the per-test result file path so suite/test names containing punctuation / whitespace / unicode still produce valid VFS paths.

currentTestDir( ) → string

Internal: the sandbox directory for the test currently executing — `TMP_ROOT/<suite-slug>/<test-slug>`. Every fixture a test mints lands under its own folder so two suites (or two tests) can never collide on a path, and the per-test cleanup in `Test.run` can drop one test's artifacts without touching another's. Outside a running test (suite-registration side effects, a standalone `execute()` repro) it degrades to `TMP_ROOT/<suite-slug>/_suite`, and to `TMP_ROOT` itself when even the suite name is unknown — so a stray write still lands inside the single root the run tears down at the end.

describeNested(v: any, depth: number, seen: { [any]: boolean }) → string

Internal: render one value nested inside a table. Strings are quoted here (they are values in a structure, so their bounds must be visible), unlike at the top level where they pass through verbatim.

describeValue(value: any) → string

Render any value as human-readable text for test output. Strings pass through unchanged; tables render structurally (`{code = "x", n = 2}`) with bounded breadth, depth, and string length; a value with its own `__tostring` uses it. Every failure message and raised error the harness reports goes through this, so a table-valued failure names its contents instead of an address.

Test.describeValue({ code = "E1", line = 4 }) --> '{code = "E1", line = 4}'

writePerTestResult(suiteName: ?, testName: ?, status: ?, errMsg: ?, failures: ?) → void

Internal: write the per-test result file. JSON-shaped: { suite, test, status: "pass"|"fail"|"skip", error?: string, failures?: { string }, ts }. `error` is the headline; `failures` holds the test's failures in the order they happened. Idempotent: overwrites a prior run's file at the same key. Failures are pcall'd because a write error must NOT block the rest of the run — the result is still in Test.results / the aggregate file.

jsonEscape(s: ?) → void

failTest(message: ?) → void

Internal: record a failure against the running test. Recording rather than throwing avoids C++ exception handling on WASM, and lets the body run on so one test can report everything that went wrong in it.

composeFailureMessage( ) → string

Internal: the one line a failing test is reported by — the failure that came first, plus a count of the ones that followed. One of these prints per failing test in a sweep of thousands, so it stays scannable and the cascade behind it travels as the ordered list instead.

resetTestState( ) → void

Internal: reset the failure record between tests. Assigns a fresh list so a copy already handed out keeps the failures it was given.

snapshotTestState( ) → void

Internal: the whole failure record as one value, for a caller that runs a body against a fresh record and puts the surrounding test's back after.

detachTestState( ) → void

Internal: the record as it stands, detached — the list is copied, so failures recorded after this point land on the live record and restoring the copy puts the record back to what it held here.

restoreTestState(snapshot: ?) → void

Internal: adopt a record `snapshotTestState` handed out.

getTestState( ) → void

Internal: read the current test state — whether anything failed, and the headline for what did.

currentFailures( ) → void

Internal: the current test's failures, in the order they happened, as a list the caller owns. A body that recorded past `FAILURES_KEPT` gets a final entry counting the rest and naming the last of them — the one that says how the body ended.

isSentinel(raised: any, sentinel: string) → boolean

Internal: whether a raised value is one of the framework's own sentinels.

standDownCurrentTest(reason: string?) → void

Internal: record a stand-down against the record that is live now and end the test it belongs to. A body captured against its own record stands down on that record, so the capture carries the reason out to the test around it and ends that one too — the stand-down means the test declined, wherever the call that declined it ran.

runBody(fn: ?, arg: ?) → void

Internal: run a body the way the runner runs a test body — under `pcall`, and with a raise recorded on top of whatever the body already recorded, as the failure that ended it. A stand-down ends the body without recording anything: a test that declined to run has produced no failure. Hands back whether the body completed and what it raised, so the caller can still recognise its own sentinels.

runHook(phase: string, fn: () → void

Internal: run one of a test's hooks — `beforeEach`, `afterEach`, a registered cleanup — on the record the test's verdict is read from, so an assertion the hook fails and an error it raises both reach the verdict as failures of the test the hook ran for. `phase` names the hook in front of every failure it records. A raise stops the hook and no more, which is what lets the runner run the rest of a test's cleanups after one of them fails.

drainAutoTeardowns( ) → void

Internal: drain the current test's auto-teardown list (LIFO). Each cleanup runs as its own hook, so a failing one records against the test that registered it while the cleanups behind it still run.

registerAssemblyOutcome(suite: Suite, name: string, raised: any) → void

Internal: account for a `describe` body that ended on a raise instead of reaching the end of its declarations. A body that raised stopped declaring where it raised, so every case below that point is missing from the suite — and the totals a run reports are the only number a caller reads. The raise therefore takes a case of its own, appended after whatever the body did manage to declare: the runner counts it, the run ends on it, and the describe's name and the raised value travel with it to the console, the per-test record, the suite report and the sweep's aggregate. A body that stood down declined rather than failed. That case is declared skipped and carries the reason, which keeps a precondition this engine does not meet reading as a skip while still accounting for the declarations the stand-down cut off.

fn( ) → void

fn( ) → void

describe(name: string, fn: () →

Define a test suite. Collects tests via `Test.it` / `Test.skip` calls inside the supplied function and registers them under `name`. Per-suite and per-test documentation (overall description + per-test pass condition) is authored as `--!desc` / `--!pass` doc-comments above the `Test.describe` / `Test.it` calls and extracted statically by the engine's doc parser (`zero_scripting::module_docs`); it is not passed at runtime. collect tests into the suite. Nested describes work — the current suite is restored when this call returns. A body that ends on a raise leaves a failing case behind naming the raise, so the declarations it never reached are answered for and the run ends on them; a body that stands down leaves a skipped case carrying the reason.

Test.describe("math", function() Test.it("adds", function() Test.expect(1+1).toBe(2) end) end)

it(name: string, fn: (TestContext) →

Define a single test within the enclosing `describe`. The test body receives an optional context `t` exposing `waitFrames`, `expect`, `fail`, and identifying metadata. per-test context for multi-frame tests.

Test.it("checks", function() Test.expect(true).toBe(true) end)

waitFrames(n: number?) → void

Wait at least `n` engine frames before continuing. Yields the running coroutine and returns control after at least `n` frame boundaries have elapsed. When invoked through a non-yieldable C-call chain the underlying `task.wait` raises; the runner catches that sentinel and treats the test as SKIPPED for that invocation. Run suites via the `tests` toolbox (`tests.run`) — or call `Test.run` from a yieldable context — to actually exercise the wait paths.

function(t) t.waitFrames(2); Test.expect(entity.exists(id)).toBe(false) end

waitOneDrawnFrame( ) → boolean

Wait for one frame the renderer draws, yielding to the engine's own frames meanwhile so a renderer that draws nothing is noticed. Returns true when a frame was drawn, false when none came inside the stall bound, and raises where the context cannot yield.

waitUntil(predicate: () → void

componentRegistered(name: string) → boolean

Whether a component type is registered under `name`, so that `component.add(name)` takes it. An authored component's asset resolves the moment its source is written; the type it declares registers when that registration drains, on a later frame, and this reads the registration through the handle's own `isRegistered()`, the ECS registry a queued `component.add` is routed by.

Test.waitUntil(function() return Test.componentRegistered("Probe") end, 120)

uniqueName(stem: string) → string

A name no earlier run and no earlier case in this engine has used, so a registry, a cache, a log scope or a VFS path keyed by name answers for the thing this case just made under it. The counter separates the cases within one engine and the random draw separates one engine's names from another's, which is what a suite sharded across parallel engines over one world needs. outlives its case still says which case minted it. random draw.

local name = Test.uniqueName("probe_material") --> "probe_material_7_412903"

encodeStable(value: any) → void

sceneRenderState( ) → string

The scene's shading state as one string two readings can be compared by: the ambient term, the directional sun, and every punctual light the renderer resolved, with the fields ordered so the same state always encodes the same way. A test that compares rendered frames with each other rests on all of them having been drawn under one shading state. This is the reading that says so: take it before the frames and again after, and two equal readings mean a difference between the frames belongs to what the test varied.

local before = Test.sceneRenderState()

waitForSteadyScene(stableFrames: number?, maxFrames: number?) → boolean

Hold until the scene's shading state has read the same for `stableFrames` frames in a row and no scene load is in flight. A scene the engine is still settling into changes what it draws over the frames after the call that changed it: a layer's entities drain, their lights leave the resolved set, and the picture moves with them. Waiting on the reading rather than on a frame count holds for as long as the machine the test runs on needs. 4; clamped to a minimum of 1.

Test.waitForSteadyScene()

withSteadyScene(body: (, attempts: ?) →

Run `body` inside a window in which the scene's shading state holds still, so the frames it takes can be compared with each other. The call waits for the scene to steady, reads `Test.sceneRenderState()`, and runs the body while a watcher reads the state again on every frame the body spans. A body whose frames were taken across a change in that state measured something the test did not vary, so it is run again on a scene that has settled — up to `attempts` times, after which the call reports what moved instead of handing back frames. Reading every frame catches a change that lands and is undone inside one window. The body measures and returns; put the assertions on what it returns. A body that runs twice records anything it asserts twice.

local frames, reason = Test.withSteadyScene(function() ... end)

rendererWork( ) → any

What the renderer says it still owes the picture, or nil where no renderer is attached to answer. Read through pcall so a build without one — an LSP pass, a harness unit test — reads nil rather than raising.

waitStill(budget: { frames: number }) → void

Hold until the renderer owes the picture nothing, spending frames from a budget the whole call shares. A renderer that keeps taking work on spends the budget once rather than once per reading, so a call that cannot get a quiet span costs a bounded number of frames whatever its attempt count.

rendererWork( ) → any

The renderer's own account of what it still owes the picture: pipeline builds its lanes hold, textures queued for the device and for release, and whether the texture-residency plan is still moving. `nil` where no renderer is attached to answer. `settled` is the word a measurement wants — the renderer owes this picture nothing, so the frames after it draw the same picture unless the scene changes — and `epoch` is what a PAIR of readings needs: it counts the runs of work taken on since boot, so an equal epoch either side of a span says nothing arrived across the whole span rather than at its two endpoints.

local w = Test.rendererWork(); if w and w.settled then measure() end

waitForSettledRenderer(maxFrames: number?) →

Hold until the renderer owes the picture nothing, and answer the reading that says so. The bound is a frame budget: a renderer that keeps taking work on is a renderer this never answers `true` for, and a test that asked has learned that rather than waited forever. Where nothing answers for the renderer at all this returns `true` with a `nil` reading, so a harness running without one measures what it came to measure.

local still, work = Test.waitForSettledRenderer()

look( ) → any

skip(name: string, fn: ((TestContext) →

Skip a test, in either of the two moments a test can be skipped. With a body, it DECLARES a skipped test: the `Test.it` shape, marked `skip = true`, so the runner counts it under `skipped` and leaves the body unrun. That is the form a `describe` takes, and a reason arriving there on its own raises naming it. Inside a running test — its body, or one of the hooks around it — a call carrying a reason alone STANDS THAT TEST DOWN: the test ends at the call and is reported skipped, and the reason travels with it to the console, the per-test record and the report. That is the shape for a test whose precondition this engine does not meet, which has nothing to verify and has earned no pass. Anything the test's hooks record around the stand-down is a failure of the test they ran for and outranks it. standing the running test down. Left out, the call stands down the test that is running, and raises where no test is running. `describe`. A stand-down ends the test rather than returning.

Test.skip("not yet", function() error("...") end)

Test.it("draws", function() if not engine.gpuCompute then Test.skip("no GPU compute") end end)

measurement(what: string) → nil

Declare that the running test's verdict is decided by how fast the host ran — a rate, a ratio between two rates, or a wall-clock bound. Such a test asks a real question about the engine and answers it differently on a loaded machine than on a quiet one, so its verdict belongs to a run whose purpose is to measure. A run that admits measurements (`Test.measurements`, which `tests.run { measurements = true }` sets) runs the body; anywhere else the call stands the test down carrying what it measures, the way any unmet precondition does. measurement the run declined. the test down and does not return.

Test.it("a take costs the run nothing", function() Test.measurement("the rate the engine publishes frames at") end)

quarantine(issue: string, why: string, opts: QuarantineOpts?) → nil

Declare that the running test's verdict is not decided by the code it covers alone — the host's GPU, the runner's load, a service outside the engine can decide it too — and hold it under the issue that says so. The body runs and every assertion in it is measured as usual; a failure is reported, named as this issue's, and counted apart from the number a merge gate reads. So the test goes on watching its subject and a red gate goes on meaning the code. It is for a test that has been seen to pass and fail over the same code. A test that fails because the engine is broken is a defect to fix, and a quarantine over one hides it — the issue is what tells the two apart, so there is no form of this call without one. A hold names the build it stands on where one build decides the verdict: `{ on = "browser" }` for a subject the web build answers differently. On every other build the case runs and counts towards the run as an unheld one does, so the sweep that reads the same code where nothing is wrong goes on gating it. Naming no build holds on all of them. retires the quarantine: closing it is the undertaking to remove the call, so the calls a checkout carries and the issues open behind them are one set, and reading them off the call sites is how that stays answerable. `#example` stands in for an issue in the harness's own cases for this call, and is taken only from a test captured with `Test.captureTestOutcome`, where it holds nothing. `"browser"`, or a list of them — for a subject one build decides and the others do not. On a build the hold does not name, the case runs and counts towards the run the way an unheld one does, so the sweep that reads the same code on that build goes on gating it. A call naming no build holds on every build. A build outside that pair is refused: a name nothing runs under is a hold that never stands.

Test.it("the readback lands", function() Test.quarantine("#1234", "the shared runner's GPU drops the device mid-batch") ... end)

Test.it("the field answers", function() Test.quarantine("#1234", "the web build's field answers 0 everywhere", { on = "browser" }) ... end)

beforeEach(fn: () → void

Register a before-each hook on the current suite. Runs before every test body in the suite. Hook errors mark the test failed rather than aborting `Test.run`.

Test.beforeEach(function() engine.mode = "edit" end)

afterEach(fn: () → void

Register an after-each hook on the current suite. Runs after every test body in the suite. Hook errors print a warning rather than aborting `Test.run`.

Test.afterEach(function() layers.active:reload() end)

expect(value: any) → any

Create an expectation builder over a value. Returns a chainable table with matchers like `toBe`, `toBeTruthy`, `toContain`, `toMatch`, `toHaveLength`, `toBeCloseTo`, and a `never` flip. throwing) so multiple expectations per test still execute.

Test.expect(1 + 1).toBe(2)

Test.expect("hello").toContain("ell")

never( ) → void

Negate the expectation

toBe(expected: ?) → void

Equal check

toBeTruthy( ) → void

Truthy check

toBeFalsy( ) → void

Falsy check

toBeNil( ) → void

Nil check

notToBeNil( ) → void

Ergonomic alias for `never().toBeNil()` — many suites expect this name.

toBeType(expectedType: ?) → void

Type check

toBeGreaterThan(expected: ?) → void

Numeric comparisons

toBeLessThan(expected: ?) → void

toBeCloseTo(expected: ?, precision: ?) → void

toContain(substring: ?) → void

String contains

toMatch(pattern: ?) → void

String match pattern

toHaveLength(expectedLength: ?) → void

Table length check

toThrow(expectedMessage: ?) → void

Function raises check. Calls the subject under `pcall` and asserts on what came back. `expectedMessage` is matched as a plain substring of the rendered raised value, so a test can pin the reason without pinning the surrounding wording.

captureFailure(fn: () →

Run a body and return the failure it records instead of recording it. Matchers report by flagging the running test, so a test that asserts a matcher rejects something would flag itself; this hands back the rendered message and leaves the surrounding test's own state untouched. A body that records more than one failure returns the headline for them — use `Test.captureOutcome` for the whole ordered list.

local msg = Test.captureFailure(function() Test.expect(1).toBe(2) end)

Test.expect(msg).toContain("to be 2")

captureOutcome(fn: () →

Run a body the way the runner runs a test body and hand back everything that would be reported for it: the failures it recorded in the order they happened, the headline composed from them, and whether a raise ended it. A raise is recorded as the final failure, which is how the runner treats one. The surrounding test's own record stays untouched.

local o = Test.captureOutcome(function() Test.expect(1).toBe(2); error("boom") end)

Test.expect(o.failures[1]).toBe("Expected 1 to be 2")

buildContext(suiteName: string, testName: string) → TestContext

Internal: the per-test context handed to a body. Built from the suite and test a body is running under, so a body reached through any entry point gets the same one.

runLifecycle(suite: Suite, test: any, betweenTeardowns: (() → void

Internal: run one test's whole lifecycle in order — `beforeEach`, the body, `afterEach`, then the cleanups registered while it ran — against a single failure record, and compose the verdict once every one of them is done. The hooks record onto the same record the body does, so a teardown that fails an assertion or raises fails the test it ran for, and its failure travels beside the body's in the order the two happened. `betweenTeardowns` runs after `afterEach` and before the cleanups. The runner passes the step that returns the engine to a state where a cleanup's writes land; a caller with no engine state to settle passes nothing.

captureTestOutcome(spec: TestSpec) → TestOutcome

Run a test's whole lifecycle the way the runner runs one — `beforeEach`, the body, `afterEach`, then the cleanups registered while it ran — and hand back the verdict composed from everything all of them recorded. The runner reads its verdict from the same place, so what this reports for a test is what a sweep reports for it. A failure a hook records names the hook it came from. The surrounding test's own record stays untouched.

local o = Test.captureTestOutcome({ body = function() end, afterEach = function() Test.expect(1).toBe(2) end })

Test.expect(o.failures[1]).toBe("afterEach: Expected 1 to be 2")

runImpl( ) → boolean

Internal: the actual run loop. Wrapped by `Test.run` so the sandbox tmp root is always torn down afterwards (see the wrapper below).

yieldToEngine( ) → void

run( ) → boolean

Run every registered suite. Resets stats, executes each test body inside a `pcall` so a runtime error marks the test failed rather than aborting the run, snapshots/cleans up leaked entities between tests, and defensively returns the scene to `edit` mode if a test leaks `play` mode. On the way out — pass, fail, OR an uncaught framework error — it always tears down the entire sandbox tmp root, so no test artifacts ever outlive the run.

local ok = Test.run()

tmpPath(relativePath: string?) → string

Build a sandboxed path for a test fixture under the CURRENT test's own folder (`TMP_ROOT/<suite>/<test>/...`). Every write a test makes should go through this so it lands inside the per-test sandbox the runner cleans up automatically — never at a hand-rolled `/source/...` path that survives the run and syncs to spacetime. Empty / non-string `relativePath` returns the test's folder itself. Called outside a running test it falls back to the suite folder, then to `TMP_ROOT` (see `currentTestDir`).

local p = Test.tmpPath("Foo.component/init.luau")

sandbox(tag: string?) → string

Create a fresh, empty sandbox container folder under the current test's tmp dir and return its absolute path. Pass it as an `into` container path to `asset.create` / `Material.Create` (`into = { path = Test.sandbox("mats") }`) so the new asset is authored under the sync-excluded `/source/tmp/tests/...` sandbox instead of the world root. The runner sweeps the folder at end-of-test, and the egress filter keeps everything under it out of the bound world's content store — so even hundreds of fixtures never pollute the user's `/source` tree or block play / push.

local r = asset.create("material", "gold", { shader = "pbr", into = { path = Test.sandbox("mats") } })

useScene(opts: { fixture: string?, additive: boolean? }?) → any

Mint an isolated scene for the current test. Duplicates the body of `opts.fixture` (a `.scene` folder) into a unique path under `Test.TMP_ROOT/scenes/` and loads it through `layers.load`. The freshly-loaded layer becomes the active root (or an additive overlay when `opts.additive == true`). The duplicate is registered for auto-teardown on the current test — when the test body finishes (success OR failure), the runner unloads the layer and removes the sandbox copy. Whatever was authored on top of the duplicate (entities, components, dirty edits) is therefore discarded automatically. Nothing the test writes lands in user content. Tests that need a richer baseline (a Player template, a Camera rig, custom lighting) pass an explicit `opts.fixture` pointing at a fixture folder of their own — useScene treats it like any other `.scene` source. path of a `.scene` folder (defaults to `Test.DEFAULT_SCENE_FIXTURE`). `additive` controls whether the duplicate loads as an additive overlay alongside whatever else is loaded, or replaces the current root (the default). `layers.find` would hand back) so callers can read `.guid` / `.name` / spawn entities into it / register additive overlays.

local scene = Test.useScene()                            -- empty root

local hud = Test.useScene({ additive = true })           -- empty overlay

local rig = Test.useScene({ fixture = "/zero/source/libs/@builtin/_canonical/static_player.scene" })

registerCleanup(fn: () → void

Push a cleanup function onto the current test's auto-teardown list. Drained LIFO after `Test.afterEach`, on both success and failure paths, so the cleanup fires even when the test body errors out. Use this when a test allocates additional resources (extra `layers.load` after the initial useScene, temp VFS paths outside the sandbox, registered MCP tools, …) that the standard useScene auto-teardown doesn't cover.

Test.registerCleanup(function() pcall(layers.unload, myRef) end)

useSceneEach(opts: { fixture: string?, additive: boolean? }?) → nil

Suite-level sugar for "mint a fresh scene before every test in this suite". Equivalent to writing `Test.beforeEach(function() Test.useScene(opts) end)` but composable — preserves any beforeEach the suite already registered and adds the useScene call after it.

Test.describe("VFS Entity", function()

Test.useSceneEach()              -- empty root scene per test

Test.it("...", function() ... end)

end)

beforeEach( ) → void

prepareTmp( ) → void

Recreate the sandbox tmp root. Removes any leftover files and creates a fresh empty directory at `Test.TMP_ROOT`. Safe to call from `Test.beforeEach`.

Test.prepareTmp()

cleanupTmp( ) → void

Remove the sandbox tmp root and everything in it. Logs a warning if the remove fails but doesn't error.

Test.cleanupTmp()

beginWorldBaseline( ) → WorldBaseline

Capture a clean-slate world baseline: snapshot every non-persistent layer (by guid + additive flag) then unload them, so suites can't depend on whatever scene the engine booted with. Persistent layers (e.g. the editor overlay) are left untouched. Holds until the booted world reports itself loaded, so the snapshot names the layers that world actually brought, and then until the unload cascade has landed, so the first suite starts on a world that has stopped moving. Pair with `Test.restoreWorldBaseline` to put the captured layers back afterwards.

local base = Test.beginWorldBaseline(); ...; Test.restoreWorldBaseline(base)

clearLoadedLayers( ) →

Put the world back to the clean slate a sweep begins from: the run's stand-in root released, and every non-persistent layer unloaded. A sweep takes its baseline once and restores it once, so a suite that loads a scene and does not put it back hands that scene to every suite after it. What the next suite then meets is not the slate it was written against — and a scene expecting player spawns without a PlayerSpawn refuses the `engine.mode = "play"` its `beforeEach` asks for, so the suite fails whole for something the suite before it did. Which suites those are depends on the order the sweep sharded them into, so the failure moves between runs.

Test.clearLoadedLayers()

restoreWorldBaseline(baseline: WorldBaseline?) → void

Restore the layers captured by `Test.beginWorldBaseline`, leaving the engine in the shape it was found. The run's stand-in root goes first, then each captured layer is reloaded by guid via `asset.resolve`; the additive flag decides root vs overlay. Per-layer pcall'd so one failed restore doesn't block the rest.

Test.restoreWorldBaseline(base)

ensureRootLayer( ) → any

Take a root scene layer for the run, so `layers.active` and every scene-scoped surface reached through it (`layers.active.camera`, `:save()`, the `sceneAuthoring` review tools, `@scene` paths) answer inside a test the way they answer from `execute`. A sweep starts each run from a clean slate with the booted scene unloaded, so `layers.active` reads nil until a test asks for a scene: this returns the active root when one is loaded, and otherwise duplicates `Test.DEFAULT_SCENE_FIXTURE` to `Test.BASELINE_SCENE` and loads it. The stand-in layer goes out with the test that took it, so a suite that never asks for a root still meets a clean slate; its source is minted once and reloaded by the next test to ask, and the runner drops that on the way out. Reach for `Test.useScene` / `Test.useSceneEach` instead when the test spawns into the scene, saves it, or asserts on its entity set — those mint a fresh scene per test and tear it down after. An edit↔play flip that is rebuilding the scene is waited out first, so the root this returns is the one the body keeps rather than a proxy the rebuild is about to replace.

local root = Test.ensureRootLayer(); Test.expect(root.guid).toBeTruthy()

releaseRootLayer( ) → void

Unload the stand-in root scene layer `Test.ensureRootLayer` loaded and drop its source folder. The next `Test.ensureRootLayer` mints a fresh one. A no-op when the run never took a stand-in.

Test.releaseRootLayer()

snapshotEntities( ) →

Snapshot the set of entity ids currently alive. Pair with `Test.sweepLeakedEntities` to despawn everything spawned after the snapshot — the safety net for entities leaked outside a test body (suite-registration side effects, crashed tests) that the per-test cleanup can't see.

local pre = Test.snapshotEntities(); ...; Test.sweepLeakedEntities(pre)

detectSpawnedEntities(preSnapshot: { [any]: boolean }) →

Compare the entities alive now against a snapshot and report every one that appeared since. Use it to assert an operation spawns nothing: the answer is the entity set itself, so it holds whatever else the world already carries — unlike a name lookup, which reports ambient content whenever the name is one the world uses too. The entity analogue of `Test.detectSourcePollution`.

local pre = Test.snapshotEntities(); op(); Test.expect(#Test.detectSpawnedEntities(pre)).toBe(0)

sweepLeakedEntities(preSnapshot: { [any]: boolean }) → number

Despawn every entity not present in `preSnapshot` (from `Test.snapshotEntities`). Unlocks destroy-locked entities first so even PlayerOwned leaks can be cleaned. Yields one frame so the deferred despawns drain before the next suite snapshots its own baseline.

Test.sweepLeakedEntities(pre)

snapshotScreens( ) →

Snapshot the UI screens currently registered, mapping each name to its current visibility. Pair with `Test.sweepLeakedScreens`, which unregisters every screen registered after the snapshot AND restores the visibility of the snapshotted screens — the safety net for UI screens a suite mounts and never tears down (which pile up as ghost screens) and for a suite that toggles a pre-existing screen's visibility (e.g. `Z.screens.hideAll`) and leaves the user's own UI hidden after the run.

local pre = Test.snapshotScreens(); ...; Test.sweepLeakedScreens(pre)

sweepLeakedScreens(preSnapshot: { [string]: boolean }) → number

Restore the screen set captured by `Test.snapshotScreens`: unregister every screen registered after the snapshot, and put each snapshotted screen's visibility back to how the run found it. Screens reloaded with a world layer come back in the restore pass, so only screens a suite mounted outside a layer get swept; a suite that hid a pre-existing screen (e.g. via `Z.screens.hideAll`) gets that screen re-shown so the user's UI doesn't stay blank after a test run. Yields one frame so the changes drain before the caller reads the screen set again.

Test.sweepLeakedScreens(pre)

residentRenderTargets( ) → number

Internal: how many offscreen render targets the renderer holds this frame. `-1` when the renderer has published nothing to read.

liveRenderFeatures( ) → void

Internal: the identities of the render features registered right now, sorted so two readings compare as strings.

liveLayerGuids( ) → void

Internal: the guids of the layers loaded right now, sorted the same way.

quiescenceReading( ) → void

Internal: one reading of every facet a queued teardown moves, facet by facet so a wait that gives up can name which one was still going.

settleWorldTeardown(maxFrames: number?) → WorldQuiescence

Hold until the work a teardown queued has landed: yields frames until every reading — live entities, loaded layers, registered render features, resident offscreen render targets, layer loads in flight — is unchanged for five consecutive frames. A despawn applies a frame after it is asked for, the render target that entity owned is reclaimed the frame after that, and a layer unload drains over several more, so a caller that yields a single frame hands the rest of that chain to whatever runs next. A test that tears down world state and then reads a count off the engine wants this between the two. A budget below the stability window cannot reach it, so it is answered `settled = false`; nought or less is answered that way without waiting a frame. change on the last frame any of them did, and is empty whenever the wait saw nothing move, so `settled` is what says whether the world had stopped or the budget ran out first. A caller that cannot reach a frame boundary is answered `settled = false` after nought frames, with `moving` naming `yield`.

local q = Test.settleWorldTeardown(); print(q.settled, q.frames)

snapshotLayers( ) →

Snapshot the layers loaded right now, by guid. Pair with `Test.sweepLeakedLayers`, which unloads every layer loaded after the snapshot — the layer analogue of `Test.snapshotEntities`, for a suite that loads a scene and leaves it standing for every suite behind it.

local pre = Test.snapshotLayers(); ...; Test.sweepLeakedLayers(pre)

sweepLeakedLayers(preSnapshot: { [string]: boolean }) →

Unload every non-persistent layer loaded since `preSnapshot`. Persistent layers (the editor overlay) are left alone. The answer names the layers it asked the engine to unload, which covers what appeared between the snapshot and now; a layer that went stays gone. Each unload lands over the frames after the call, so a caller reading the loaded set straight back waits for what it asked for — `Test.waitUntil` on `Test.snapshotLayers`, or `Test.settleWorldTeardown` when it wants the whole cascade behind it.

Test.sweepLeakedLayers(pre)

snapshotRenderFeatures( ) →

Snapshot the render features registered right now, mapping each guid to the asset identity it was created from. Pair with `Test.detectLeakedRenderFeatures`, which names the ones registered after the snapshot. A feature draws on every frame of every suite behind the one that registered it, so one left standing changes what a later suite's pixel and draw-call readings measure.

local pre = Test.snapshotRenderFeatures()

detectLeakedRenderFeatures(preSnapshot: { [string]: string }) →

Name the render features registered since `preSnapshot`, counted by identity. A suite that re-registers an identity replaces the live instance under a new guid, so what a suite hands over is which identities are running and how many of each, not which guid is carrying them. The answer is a report rather than a teardown. A render feature is brought up by the system that needs it, and that system keeps its own record of whether it is live: a feature destroyed from outside leaves the system believing it is still running, so it never brings it back and everything that feature drew is missing from then on. Naming the suite that left one is what a reader can act on. The answer covers the identities the suite ADDED to the set it was handed. The set as the suite leaves it is what the next boundary opens against, so an identity the suite took down is the baseline every suite behind it is measured from. sorted.

local left = Test.detectLeakedRenderFeatures(pre)

snapshotGpuLabels( ) →

Snapshot the GPU resources the allocator holds right now, mapping each label to how many allocations carry it. Pair with `Test.detectLeakedGpuLabels`, which names the labels a suite added and left standing. A GPU resource created under a name — a `compute` storage target, a 3D texture, a history pair — answers to that name for as long as the engine runs, so whoever names one owns releasing it: a root scene load and `renderer.collect` both leave it where it is.

local pre = Test.snapshotGpuLabels()

gpuLedgerReady(frames: number?) → boolean

Wait for the device allocator's ledger to be sampled, and say whether this engine has one at all. `renderer.gpuMemory().allocator` is the device allocator's own record, so it is there on a backend that allocates its own memory and absent on one whose host allocates for it — a browser's WebGPU device among them — and it arrives on a sampled frame rather than on the call that asks. Every reading built on `Test.snapshotGpuLabels` asks this first: on a device with no ledger each of them answers with silence, which reads exactly like a suite that left nothing behind, so a case stands itself down here instead of passing on a reading it never took.

if not Test.gpuLedgerReady() then Test.skip("this device keeps no allocator ledger") end

gpuLabelsMatching(needle: string) →

Name every GPU label the allocator holds right now that contains `needle`. A suite that gives its fixtures a prefix of its own reads its whole footprint this way, whatever the sweep around it has allocated, and whatever earlier run of the same suite left standing — the reading is an absolute one, so a leak already in the ledger is still reported.

local mine = Test.gpuLabelsMatching("_test_myfixture")

detectLeakedGpuLabels(preSnapshot: { [string]: number }) →

Name the GPU labels the allocator holds now that `preSnapshot` did not, and the ones it now holds more allocations under. This is the reading for a suite whose fixtures carry engine-given labels it cannot pick out by name; a suite that names its own reads them with `Test.gpuLabelsMatching`, which answers the same on a second run in the same engine. The name is the only handle a named GPU resource has, so the case that named one is the one that can release it, and this answer is the list of what the suite left standing.

local left = Test.detectLeakedGpuLabels(pre)

computeIdentity(row: any) → string

Internal: the identity one compute resource answers to across two readings: the key it is filed under, and the frame it was created on. A key is reissued when the owner makes a new resource under the same name, and the creation frame is what separates that new resource from the one it replaced.

computeInventoryReady(frames: number?) → boolean

Wait for the engine to publish a compute inventory, and say whether it has one to publish. `compute.observe()` reports `published` false until a renderer has built the listing, and the three readings below answer an inventory in that state with an empty map, which reads exactly like an engine holding nothing. Every reading built on `Test.snapshotComputeResources` asks this first, so a case stands itself down here instead of passing on a reading it never took.

if not Test.computeInventoryReady() then Test.skip("this engine publishes no compute inventory") end

snapshotComputeResources( ) →

Snapshot every GPU resource the compute subsystem holds right now, one entry per resource. Pair with `Test.detectAddedComputeResources` and `Test.addedComputeBytes`, which name and price what stands now that the snapshot did not hold. `Test.computeInventoryReady` is what a case asks before the first of them. `renderer.gpuMemory().compute` is one figure over every compute resource in the engine, so a case reading it as a delta across a take-down reads whatever every other owner allocated and released across that same span. A shader an earlier suite left loaded, given back while the span is open, takes the closing reading BELOW the opening one and the delta comes out negative, which is a figure no take-down could have produced, on a suite that did nothing wrong. Reading the resources themselves answers for what the case's own subject left standing, and a give-back by anything else is not in it.

local pre = Test.snapshotComputeResources()

addedComputeBytes(preSnapshot: { [string]: number }) → number

What the compute resources added since `preSnapshot` cost together, in bytes. The figure a case asserts back to nought after a take-down, in place of a `renderer.gpuMemory().compute` delta that carries every other owner's traffic across the same span.

Test.expect(Test.addedComputeBytes(pre)).toBe(0)

snapshotTheme( ) → string

Snapshot the UI theme active right now, so a suite that switches theme can be put back on the one it was handed. A colour a suite reads — a highlighter segment, a widget's token — resolves through the active theme at the moment of the read, so the theme standing at the end of one suite decides what every suite behind it reads. Pair with `Test.restoreTheme`.

local pre = Test.snapshotTheme(); ...; Test.restoreTheme(pre)

restoreTheme(preSnapshot: string?) → string

Put back the theme captured by `Test.snapshotTheme` when the active one has moved off it, and name what was standing there instead. the snapshot was put back. nil covers the three cases that leave nothing to name: the theme still stands where the snapshot found it, there was no snapshot to put back, and the put-back was refused — the refusal is written to the engine log as it happens.

local left = Test.restoreTheme(pre)

snapshotSkyFallback( ) → boolean

Read whether the sky fallback is armed. Pair with `Test.restoreSkyFallback`, which puts that reading back. The fallback is engine-wide and it outlives the scene its capture was taken from: coverage no reflection probe claims is shaded by the captured sky wherever it is armed, so a suite that rendered a sky hands every suite behind it a lit environment, and one that stood the fallback down hands them a dark one. Either way a case reading absolute pixel values off a surface reads a different number for what ran before it.

local pre = Test.snapshotSkyFallback(); ...; Test.restoreSkyFallback(pre)

restoreSkyFallback(pre: boolean) → string

Put the sky fallback back to the reading `Test.snapshotSkyFallback` took, and say whether it had to. Arming is refused while the sky slot holds no capture, so restoring an armed reading over an engine that has none leaves it disarmed and reports the attempt. "disarmed" — and nil when nothing had to be put back.

local left = Test.restoreSkyFallback(pre)

publishOpenBoundary( ) → void

Internal: publish the innermost open boundary as the current one.

openSuiteBoundary( ) → SuiteBoundary

Read the live state a suite is about to be handed — the layers loaded, the render features registered, the theme active and whether the sky fallback is armed — so the state it hands on can be compared against it. Pair with `Test.closeSuiteBoundary`, which drains the suite's teardown and reports what crossed. The suite envelope opens a boundary before it loads a suite and closes it after, and the one currently open is published as `Test.suiteBoundary` — so a body reads the world its own suite was handed, and a boundary the body opens nests inside it.

local pre = Test.openSuiteBoundary()

closeSuiteBoundary(suite: string, pre: SuiteBoundary) → SuiteHandover

Close a boundary opened by `Test.openSuiteBoundary`: unload the layers the suite loaded and left, name the render-feature identities it left registered, put back the theme and the sky fallback it was handed, and write a line to the engine log for each of the four that has something to say. This is the per-suite handover, so a caller running one suite after another has one call to make between them. The boundary it names leaves the open set, so `Test.suiteBoundary` goes back to the one around it. It answers for what is standing, and it spends no frames finding out: a caller that needs the queued teardown to have landed before it reads a count calls `Test.settleWorldTeardown` around its own reading, and pays the frames where it wants them. What it answers for is what the suite ADDED to the world it was handed: a layer that appeared between the two reads is unloaded, and a render-feature identity that appeared is named. A layer or a feature the suite took away is the suite's own doing and stands as the suite left it. given, the layer guids it asked the engine to unload, the feature identities left standing, the theme the suite left active when one was put back, and how it left the sky fallback when that was put back too. The same record is published as `Test.lastSuiteHandover`.

local left = Test.closeSuiteBoundary("vfs", pre)

sourceEntryName(e: any) → string

snapshotSourceContent( ) →

Snapshot the set of top-level `/zero/source` entry names that exist before a suite runs. Paired with `Test.detectSourcePollution` to flag content a suite leaks OUTSIDE its sandbox — world state that would bleed into later suites (and the publish gate). The world-content analogue of `Test.snapshotEntities`.

local pre = Test.snapshotSourceContent()

detectSourcePollution(pre: { [string]: boolean }) →

Compare the current top-level `/zero/source` entries against a pre-suite snapshot and return every NEW entry that isn't engine- or runner-managed. A non-empty result means the suite left content at the world root — pollution it must instead sandbox under `Test.TMP_ROOT` or remove via `Test.registerCleanup`.

local leaked = Test.detectSourcePollution(pre)

snapshotSourceSync( ) → SourceSyncMark

Snapshot what holds `/zero/source` and how far the engine has got materialising the bound world's own content into it. Two marks bracket a suite and feed `Test.sourceDiffAttributable`, which reads them to say whether the entries that appeared at the world root across that window are the suite's doing.

local mark = Test.snapshotSourceSync()

clear( ) → void

Clear all suites and reset stats / leaked-id tracking. Use this to re-run the suite from a clean state (in particular: re-runs in the same execute() batch).

Test.clear()

getResults( ) →

Get the detailed result records from the last `Test.run`.

local rs = Test.getResults()

getStats( ) → Stats

Get the aggregate stats from the last `Test.run`.

local s = Test.getStats(); print(s.failed)

bySuite(results: { Result }) → void

Suite discovery lives in the `tests` toolbox, not here Test suites are registrable `.testSuite` assets. Discovery + running is the `tests` toolbox's job: `tests.list` enumerates them via `asset.list("testSuite")` + `asset.resolve`, and `tests.run` runs each through its own `AssetRef:run()` (which loads + runs only that suite). This module stays a pure test framework (describe/it/expect/run + lifecycle/isolation helpers) — it does not discover or batch-run suites. Report generation (used by the `tests` toolbox)

generateMarkdownReport(stats: Stats, results: { Result }) → string

Render the engine test results as a Markdown report (the format written to `/source/tmp/test_results.md`).

local md = Test.generateMarkdownReport(Test.getStats(), Test.getResults())

emit(s: ?) → void

generateJsonReport(stats: Stats, results: { Result }, suites: { SuiteTiming }?) → string

Render the engine test results as a machine-readable JSON document. This is the format the `tests` toolbox saves for diffing runs (`tests.compare`). Consumers should index `results` by `(suite, test)`.

local j = Test.generateJsonReport(Test.getStats(), Test.getResults())