test-writing

Test Writing

Output philosophy

Tests communicate two things: what passed and what failed. Everything else is noise. Model output on prove, go test, and Plan 9's /bin/test -- not JUnit XML rendered as prose.

The ok / FAIL convention

Every assertion or logical group prints exactly one line:

  ok  mkdir
  ok  rename
  ok  link (nlink=2)
FAIL  symlink (expected target 'foo', got 'bar')

Rules:

• ok is lowercase, left-aligned to 6 chars ( ok ).
• FAIL is uppercase, left-aligned to 6 chars (FAIL ).
• skip for precondition-gated tests (skip fuse (no /dev/fuse)).
• After the tag: a terse noun phrase, not a sentence.
• Parenthetical detail only when the assertion carries a value (nlink=2, pid 4821).
• Summary line at the end: 7/7 posix sanity ok or 6/7 posix sanity FAIL.

Rust #[test]

Rust test output is managed by cargo test (or nextest). The convention is in the test name, not in println!:

#[test]
fn invariant_rename_over_non_empty_dir_returns_enotempty() {
    // ...
    assert_eq!(err, Error::DirectoryNotEmpty);
}

Custom assertion helpers should panic with terse messages:

fn assert_nlink(store: &MetadataStore, ino: Ino, expected: u32) {
    let attr = store.get_inode(ino).unwrap().unwrap();
    assert_eq!(attr.nlink, expected, "ino {ino:?} nlink");
}

Go testing.T

func TestInvariant_ReconcilerSurvivesPerWorkspaceError(t *testing.T) {
    // ...
    if got != want {
        t.Fatalf("workspace B status: got %v, want %v", got, want)
    }
}

Use t.Fatalf (not t.Errorf + t.FailNow). One call, one line.

Python pytest

Let pytest handle reporting. Assertions use bare assert:

def test_invariant_chunk_key_is_deterministic():
    a = chunk_key("ws-1", b"hello")
    b = chunk_key("ws-1", b"hello")
    assert a == b

For parametrized output, use pytest.mark.parametrize -- it generates one ok line per case automatically.

CI integration