Testing
Sun has builtin unit testing: declare tests with test_function, assert with
std.test, and the compiler produces a test runner for you. Tests never
appear in production binaries or .moon bundles.
using std;
module geometry {
function addOne(n: i32) i32 {
return n + 1;
}
test_function addsOne() {
std.test.assert_eq(geometry.addOne(1), 2);
}
}
function main() i32 throws {
return 0;
}
manifest { libraries: ["stdlib.moon"] }$ sun test program.sun
PASS geometry.addsOne
1 passed, 0 failedDeclaring tests
A test uses test_function in place of function, takes no parameters, and
returns void. Tests can throw by default. Reaching the end or writing return;
passes the test; an exception that escapes fails it. A panic aborts the entire
test process.
/** Checks arithmetic and propagates any assertion failure to the runner. */
test_function arithmetic() {
std.test.assert_eq(2 + 2, 4);
}Both sequential and parallel runners handle exceptions. Assertion failures carry bounded diagnostic text. Other uncaught exceptions fail the test even when no diagnostic is available. At that terminal catch, the runner writes the exception type and readable original stack trace to standard error once. Incomplete or disabled traces include their capture status. Reporting does not call user message formatters or consume the retained exception. An explicit trace printed by the test before rethrowing can intentionally appear in addition to the runner's report.
Tests are module-level declarations. They cannot appear inside classes,
interfaces or function bodies, cannot be public (they are never
importable), cannot take type parameters, and cannot be named main.
A test's name is reported qualified by its module (geometry.addsOne), so
the same test name in two different modules is fine. Two same-named tests in
one module are a duplicate-declaration error.
Where tests live
Tests can sit inline, next to the code they exercise. Privacy is
module-scoped, so a test inside module geometry can call the module's
private functions directly — no exporting things just to test them.
Larger suites go in test files: .sun files listed under test_files:
in the manifest, loaded only when compiling tests. A test file reopens the
module it tests to reach its private items:
manifest {
source_files: ["geometry.sun"]
test_files: ["geometry_tests.sun"]
libraries: ["stdlib.moon"]
}test_files: is also accepted inside per-OS target: blocks.
Production builds strip test functions before analysis, so a test may freely
reference helpers that exist only in test_files. Everything else — classes,
helper functions, module variables declared outside test_files — stays in
the production build, so shared fixtures and helpers that should not ship
belong in a test file.
Reusing the library's module name does not change that separation: even public
helpers and types in test_files are excluded from the production library.
Their names must still avoid collisions within the module during a test build.
The standard library tests itself this way: each stdlib/<area>_tests.sun
sits next to the file it tests and is listed under test_files: in
stdlib/stdlib.sun, with shared fixtures in stdlib/std/fixtures_tests.sun.
Tests use the library module directly, such as std.linalg or std.io, and
keep short names unless a collision requires a more specific name.
sun test stdlib/stdlib.sun runs the whole suite from a workspace checkout;
none of it ships in stdlib.moon. The tls bundle does the same with
tls/https_client_tests.sun, listed in tls/tls.sun.
Running tests
sun test compiles the program with its tests and runs them under the JIT:
sun test program.sun # parallel (default)
sun test program.sun --test-sequential # one after anotherThe exit code is 0 when every test passes, 1 otherwise.
Compiling with -c also emits a second binary, <output>_test, whenever the
program has tests:
$ sun -c -o app program.sun
Successfully compiled to: app
Successfully compiled test binary to: app_test
$ ./app_test --test-sequentialPass --no-test to skip the test binary. A program with tests but no main
— a library — compiles to just the test binary.
Filtering
--test-filter <pattern> picks which tests run. Like --test-sequential it
is a runtime argument of the test binary, so no recompile is needed:
sun test program.sun --test-filter geometry.midpoint # exact dotted name
sun test program.sun --test-filter geometry.* # everything under geometry
sun test program.sun --test-filter geometry # same, no star needed
./app_test --test-filter geometry.midpoint # compiled binary tooThe flag repeats: a test runs when it matches any given pattern. A pattern
matches a test's dotted name exactly, as a module prefix (geometry selects
geometry.midpoint), or as a trailing-star prefix (geo*). The summary
counts only the tests that ran, and a filter that selects nothing reports
0 passed, 0 failed and exits 0.
Parallel by default
The runner starts one thread per test, then joins and reports in declaration
order, so the output is deterministic. Tests therefore must not share
unsynchronized state: a module-level var written by two tests is a data
race. Either protect shared state with std.thread.Mutex, or pass
--test-sequential (a runtime argument, so no recompile) to run tests one
after another in declaration order.
Assertions
Assertions return void on success and throw std.test.AssertionError on
failure. The exception carries code 10 and bounded inline diagnostic text.
Write std.test.assert(condition); directly in a test.
| Function | Meaning |
|---|---|
assert(cond) | Fail when cond is false |
assert(cond, "why") | Same, with an explanation in the output |
assert_eq(expected, actual) | Fail when the values differ, showing both. Overloaded for every primitive and for String (by content) |
assert_ne(a, b) | Fail when the values are equal |
fail("why") | Fail unconditionally |
For types without an assert_eq overload, write the comparison yourself:
std.test.assert(a.equals(b), "explanation");.
Handle expected failures with try and a concrete catch. Fail explicitly if
the operation returns successfully:
/** Checks that invalid indexing throws the expected exception type. */
test_function rejects_invalid_index() {
var values = std.Vec<i32>(std.mem.global_allocator, 1);
try {
values.at(10);
std.test.fail("expected an out-of-bounds exception");
} catch (error: std.IndexOutOfBoundsError) {}
}Unexpected exceptions can propagate directly to the runner. The old result unwrapping helpers are no longer needed.
Tests require the standard library (stdlib.moon in the manifest, or
--moon stdlib.moon); the assertions and the runner live there.
Fixtures
Sun needs no fixture framework: a fixture is an ordinary class whose init
does the setup and whose deinit does the teardown.
using std;
/** Tests directory setup and cleanup. */
module config {
/** Owns an empty directory for this test process. */
class TempDir {
public var path: String;
/** Creates a directory whose name includes the process ID. */
init() throws {
this.path = String("/tmp/sun_config_test_");
this.path.append(std.process.pid());
std.io.make_dir(this.path, 448);
}
/** Removes the empty directory when the fixture leaves scope. */
deinit() { try { std.io.remove_dir(this.path); } catch {} }
}
/** Checks the directory while the fixture keeps it alive. */
test_function createsScratchDirectory() {
var dir = std.test.expect_system(config.TempDir()); // setup
std.test.assert(std.io.is_dir(dir.path));
// teardown runs here or when try returns an assertion failure
}
}Two language guarantees make this complete:
- A local is dropped exactly once at the end of its scope, so teardown always runs after a passing test.
- Propagating a failed assertion drops every live local before returning, so teardown also runs when the test fails.
A test can hold several fixtures. Fallible setup uses init(...) throws.
If setup throws, initialized fields are released and the test fails.
In the editor
The Sun VSCode extension shows every test_function in the Test Explorer,
grouped by entrypoint and file, with run icons in the gutter. Tests are
discovered through the entrypoints list of your sun-config.json (the
sun.sun_configs setting names the config files; the workspace root's is
found by default), so the whole tree appears without opening a file.
Running a selection passes --test-filter for each chosen test. The extension
runs only the compiled binary named by test_binary_name in sun-config.json,
and checks that it is at least as new as every source. Build tests before running
them in the editor. If the binary is unconfigured, missing, or out of date, the
selected tests show an error asking you to build or rebuild them. The extension
does not JIT-compile tests. A failed assertion's message appears on the test.
Debugging the runner
--debug writes the synthesized runner source next to the other debug
artifacts, so you can see exactly what the test binary's main does:
sun test --debug program.sun # writes program_debug/test_runner.sun
sun -c --debug -o app program.sun # test build writes app_test_debug/