Docs/Tooling

Unit tests

Run package tests with testing.T, private or external test packages, tang reports, JSON events, and saved results.

Write and run a test#

Name test files with the _test.oc suffix. Declare top-level functions whose names start with Test, each accepting exactly one *testing.T argument and returning no values. Run ocean test in the package directory, or pass one directory or Ocean file selecting a package. Ordinary build and run commands exclude test files, so they are never included in normal executables or library objects. ocean check and ocean build --check validate both same-package and external _test.oc files in the selected package without executing tests. Test files from imported dependencies remain excluded. Tests from imported dependencies do not run as part of the target suite.

Ocean
// arithmetic_test.oc
package arithmetic;
import "testing";

func TestAdd(t *testing.T) {
    if (Add(2, 3) != 5) t.Errorf("wanted {}, got {}", 5, Add(2, 3));
    t.Run("negative", func(t *testing.T) {
        if (Add(-2, -3) != -5) t.Fatal("negative addition failed");
    });
}

The compiler generates a temporary test executable. Its entry point replaces the production main only for this test build. The command preserves the current working directory and removes the executable when finished. An empty suite succeeds.

Internal and external test packages#

A test file declaring the same package as the ordinary source files shares their private functions, types, and variables. A test file declaring <package_name>_test belongs to a separate external package in the same directory. External tests import the package under test and can access only its exported API. Both kinds run in the same suite. The external package is allowed only in _test.oc files.

Ocean
// api_test.oc, beside package arithmetic
package arithmetic_test;
import "example.com/project/arithmetic";
import "testing";

func TestPublicAPI(t *testing.T) {
    if (arithmetic.Add(2, 3) != 5) t.Error("unexpected sum");
}

The testing.T interface#

Each package runs a serial phase: its Test functions start one at a time. A call to t.Parallel() pauses the calling test and lets the next serial test start. Once that package finishes its serial phase, the paused tests resume. Multiple packages run concurrently, and all active tests share one command-wide budget of 16 workers by default. -t N changes that shared limit; --single-threaded sets it to one. Parallel never bypasses the limit. Paused tests retain parked native threads for their stacks but release their active worker slots.

Run(name, callback) runs a subtest until it finishes or pauses. A parallel subtest resumes after its parent body returns. Parents release their worker slot while waiting for children and run Cleanup after every child finishes. Child failures propagate to the parent. Ordinary defers run on body exit; use Cleanup for resources needed by parallel children. Parallel must be called from the test’s own thread, at most once, before cleanup. The previous Parallel(name, callback) API is removed. Error marks failure and continues, while Fatal stops the current test and runs its deferred cleanup.

The testing.T interface reference
APIBehavior
Run(name, callback) boolRun a subtest until it finishes or calls Parallel.
Parallel()Pause this test until the parent serial phase ends, then resume within the shared worker limit.
Error / Errorf / FailMark failure and continue.
Fatal / Fatalf / FailNowFail and stop the calling test.
Failed / Skipped / NameInspect the test state or slash-separated name.
Log / LogfAttach output to the test.
Skip / Skipf / SkipNowStop and mark skipped unless already failed.
Cleanup(func())Register cleanup in reverse execution order.
Helper()Accepted for assertion helper compatibility.
Ocean
func TestConcurrent(t *testing.T) {
    t.Parallel();
    // Runs after this package’s serial phase.
}
func TestCases(t *testing.T) {
    t.Run("first", func(t *testing.T) {
        t.Parallel();
        // Resumes after the parent body returns.
    });
}

Live Tang display and JSON events#

Interactive terminals show a live tang-style TUI implemented with the standard term/tui library. It displays running and completed tests, nested subtests, recent output, status counts (▶ / ⏸ / ✓ / ✗ / ∅ / ∑), and elapsed time. The display handles resizing. Use arrow keys or Page Up/Page Down to scroll, f or End to resume following recent tests, and q or Ctrl+C to stop the suite.

After execution, the live view is cleared and the final report follows tang’s static Messages and Summary layout, with nested failure and skip details, aligned package and suite counts, and ✓ / ✗ / ∅ / ∑ / ⏱ columns. Passing details in the final report are hidden unless -v or --include-passed is set. NO_COLOR, including an empty value, and --no-color disable colors while retaining live redraws. Redirected output and saved text reports stay plain. Test rows use === RUN, === PAUSE, === CONT, and --- PASS/FAIL/SKIP statuses with running, paused, failure, and skip styling. Completed packages fold down to their package heading, counts, and elapsed time. Multi-package runs print one combined Summary table with one row per package and aggregate test counts. Each package row shows its own elapsed time; the totals row shows command wall time. Failure messages remain grouped by package. Saved text reports use the same combined table.

Terminal
ocean test .
ocean test . -v
ocean test . -t 4
ocean test . --single-threaded
ocean test . --notty
ocean test . --outfile results.txt
ocean test . --jsonfile results.jsonl
ocean test . --json --outfile results.txt --jsonfile results.jsonl
ocean test . --timeout 30s
NO_COLOR=1 ocean test .

--json emits one JSON event per line on stdout; --jsonfile saves the same event stream while keeping the human report. Events contain Time, Action, Package, Elapsed in seconds, and optional Test and Output fields. Actions are start, run, output, pass, fail, skip, pause, and cont. Arbitrary stdout and stderr are wrapped in package output events, keeping JSON valid. The final package result reflects the actual process exit, including timeouts. Exit status is zero for success and nonzero for test, compile, reporting, timeout, or process failures.

Compiler and library requirements#

Use the matching testing, threads, and sync packages from the standard-library checkout selected by OCEAN_SRC, or install the updated compiler and source library together. Test execution requires a native host target; WebAssembly tests are not supported. The test executable is built separately without reusing normal package object-cache entries. Multiple package locations are accepted per invocation. Use ./... for all packages beneath the current directory, or engine/... for engine and its subpackages, including the base when it contains Ocean source. Hidden directories, vendor, node_modules, and directory symlinks are skipped. Overlapping selections run once. Packages run concurrently and share one configured execution-worker budget. Multi-package results use module-qualified package paths, with functions grouped beneath each package in one live TUI. Report files include every selected suite, and any package failure produces a nonzero exit status. The live frontend is shipped as source in testing/internal/display and uses the matching term/tui package. It is compiled and cached separately from the test binary. If the frontend is unavailable, Ocean falls back to the final text report.

Terminal
ocean test --help