Anatomy of a Test

Ha, I happen to have exactly this test for my secret side project, so we can compare notes!

test "basic job scheduling" {
    var env: TestEnv = undefined;
    env.init(.{});
    defer env.deinit();

    try env.pr_create(.{});
    try env.merger_run_once();
    try env.worker_run_once_async();

    try env.expect_jobs(snap(@src(),
        \\1   565070d q refs/pull/1/head
        \\
    ));

    try env.pipe.rendezvous();
    try env.expect_jobs(snap(@src(),
        \\1   565070d r refs/pull/1/head
        \\
    ));

    try env.pipe.rendezvous();
    try env.worker_run_once_await();
    try env.expect_jobs(snap(@src(),
        \\1   565070d t refs/pull/1/head
        \\
    ));
}

• Yeah, a big part of testing is resource management. Historically, this was achieved using setUp / tearDown hooks, popularized by xUnit, but this is the case of patterning over a language deficiency. We got using in JavaScript like yesterday, and Java's try-with-resources in Java 7, well after the setup/teardown pattern was established. Before that, we only had try-finally, and it's a poor fit for tests, as it doesn't allow for nice composition of several resources (as you'll have to nest things). Absolutely no need to use that these days, just use your language's built-in idiom for managing resources, be it RAII, using or with. Honorable mention of pytest's auto-magic fixtures though, as they are sweet (but, again, it's a problem with with that it eats an indentation level).
• When I write function/module level "unit-test", I like just composing fixtures, but I usually prefer testing at the physical public interface (actual IO), and to have just one core test suite, so I typically have a TestEnv object that does all of:
  • resorce management,
  • encapsulation of the API under test to avoid churn,
  • providing helper "assertion" methods.
• The undefined stuff is just a Zig idiom for in-place initialization, which I like for pointer stability, not something you'd have to / be able to think about in a higher level language.
• As mentioned, I try to encapsulate not only the API for creating things, but actually also the act things as well. Furthermore, in this case the system under test is multiprocess, so I have to have a helper for shelling out and capturing the output.
• I do love snapshot testing. Here, it is a bit of system/test co-design: I snapshot test the output of the "list jobs" command. That command is specifically designed to produce snapshot table output, but it is also useful in its own right. I would assume for your thing at some point you'd also want to debug the state of jobs?
• One part of co-design is that the tests passes a --testing output to the list jobs command. While normally the listing includes timestamps, they are elided for tests. I do love to control time, but this thing here is multiprocess, and I deliberately decided that I want to test the real thing, and mocking clocks across processes is tricky.
• Because this is whole system test, I check not only that a job is scheduled, but that it is also run. Two tricks here. First, while normally I expect the system to run an event loop and deal with jobs as event happen in real time, for tests I have an explicit "run for just one step" mode which gives deterministic results, and allows me to observe intermediate results (jobs queued, running, finished with true). And this is also part of test driven design, because this forces the whole system to be passable and resumable, which means that it can be safely killed and restarted at any moment, which is not something you get for free but as a result of carefully adjusting consistency semantics to make it possible.
• Even with "one step" semantics, sometimes there isn't a useful pause for intermediate states, so I added a bit of pipe2 trickery to pause subordinate processes when needed.
• String test names are <3