Files
worklane/docs/testing.md
T

6.6 KiB

Testing

What to run before committing, the fixtures, and what rustfmt and clippy are set to.

  • Run make check before committing: cargo fmt --check, then cargo clippy --all-targets -- -D warnings, then cargo test, cheapest first. That is the whole of the enforcement, and it is deliberate rather than a stopgap: this repo has no CI and does not want any, and a git hook is a per-clone opt-in the way blame.ignoreRevsFile is, so neither can be relied on. What was missing was one name to type, so the two rules below are a command and not a memory. -D warnings is what makes clippy's opinion an exit code; a warning printed into a wall of cargo output is unread, not clean. The completion checks are inside cargo test rather than a target of their own, since a second thing to remember is the problem this solves

  • Run one suite: cargo test

  • Tests use assert_cmd and assert_fs for CLI testing

  • setup_worklane() creates temp .worklane/ with the four flow status folders pre-created, plus campaigns/ in cmd_campaign.rs, which is also where the on-demand creation is tested from a board without it. The fixtures deliberately do not create discarded/, so every discard test runs against a board that predates the status and mv_creates_the_discarded_directory_on_a_board_that_predates_it is not the only thing exercising the on-demand creation

  • create_ticket() writes fully-formed markdown files directly (no -- separator for positional args in test commands)

  • Every unit-test fixture directory goes through util::Fixture, and nothing calls remove_dir_all at the end of a test. Fixture::new(prefix) makes a uuid-named directory under the system temp dir and its Drop removes it, which is the only shape that also runs when an assertion fails — a trailing line does not, and a failing test is exactly when a fixture is most likely to be stranded. That was b74dc5a: /tmp reached 18363 of these and filled the disk, failing a link step and then a git add with "No space left on device", an error naming neither the tests nor what they left behind

  • Fixture derefs to Path and also implements AsRef<Path>, because the two reach different call sites: a parameter typed &Path is a coercion site and one bound by impl AsRef<Path> is not. Fixture::child(name) points the fixture at a directory inside itself while still removing the parent, which is the tree project_tree needs. The prefix earns its place on the one path that is ever left behind, which is why this is a small guard rather than assert_fs::TempDir — that names its directories .tmpXXXXXX, which says nothing about whose they are

  • WORKLANE_KEEP_FIXTURES=1 cargo test keeps the fixtures and prints each path. Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, and Fixture::swept() turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment

  • Verify a claim about leaked fixtures against a clean temp dir, not against /tmp. TMPDIR=/tmp/scratch cargo test then count what is left in it: /tmp still holds the historical leak, so counting there measures the past rather than the change

  • In tui.rs, write_member_card is write_tagged_card plus a Campaign field and write_campaign puts a campaign on disk, creating the campaigns directory as it goes — board_dir() deliberately does not, so every test that does not write one is also the test that a board with no campaigns draws. picker_rows cuts the picker's list out of the frame by its own geometry, for the reason overlay_title_row exists: a card carries the same campaign label, so a search over every row finds the board rather than the list

  • cargo clippy --all-targets is clean, and make check is what says so. Keep it clean, and do not silence a lint that is pointing at something real. The only two allows in the tree sit on the create_ticket fixtures in cmd_mv.rs and cmd_show.rs, each carrying the reason and what would replace it

  • cargo fmt --check is clean too, make check runs it first, and rustfmt.toml is what makes that affordable. rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:

    setting value why
    max_width 100 The tree's own habit, and the measured optimum: 90 costs 268 hunks and 120 costs 194, against 161 at 100
    fn_call_width 75 A call stays whole if it fits in three quarters of the line. rustfmt's default of 60 is what expanded 276 of the 305 hunks the default config wanted
    chain_width 65 The same for a method chain
    struct_lit_width 30 A small struct literal stays whole, so Size { width: 120, height: 20 } is not six lines

    The numbers were measured, not chosen. Default rustfmt wanted 305 hunks and would have added 1418 lines of pure layout, because its sub-widths sit far below the 100 columns this tree is written to. use_small_heuristics = "Max" went the other way, 308 hunks and 796 lines removed, one-lining if/else and collapsing struct literals that were split on purpose. Coordinate descent over the stable width knobs landed here, at 161 hunks, and 98 of those are rustfmt joining calls that fit rather than breaking them. Sweeping any one of these four in either direction makes the diff bigger, so do not adjust one by eye; measure it the same way, with cargo fmt --check | grep -c '^Diff in'

    • What this does not buy: rustfmt has no rule for "keep parallel arms parallel", so a match whose arms are one line and four lines depending on the length of their contents is what it produces, and that is accepted. Reach for #[rustfmt::skip] only where the layout carries meaning a reader needs, not to win an argument about density
    • Do not add an unstable option. cargo fmt on stable ignores them with a warning, so the tree would format differently for whoever ran nightly
    • Sixteen lines still run past 100 columns and every one of them is a single string literal, a test fixture or an error message rustfmt cannot break. format_strings is deliberately left at its default: turning it on would let the formatter rewrite message text, and a message is prose. So max_width is where rustfmt breaks lines, not a limit the tree keeps
    • The reformat is 73ffcad, and .git-blame-ignore-revs names it so git blame looks through it. Turn that on once per clone with git config blame.ignoreRevsFile .git-blame-ignore-revs. A commit belongs in that file only if its diff is pure layout