Testing

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 failed

Declaring 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 another

The 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-sequential

Pass --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 too

The 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.

FunctionMeaning
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:

  1. A local is dropped exactly once at the end of its scope, so teardown always runs after a passing test.
  2. 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/