Write Tests

Golden rules

• Use TestBuilder — never construct Context manually.
• Assert with expect(&ctx).to_have_instances(vec![...]) — never index ctx.instances.
• Async-first: #[tokio::test] + .run().await is the canonical entry.

TDD

1. Read 2-3 tests in the same *_test.rs and copy the pattern
2. Write failing test → just test → confirm RED
3. Ask before implementing
4. Implement minimal code → GREEN → just format

Quick start

use {
  crate::{
    instance::{FixableInstance::*, InstanceState, SuspectInstance::*, UnfixableInstance::*, ValidInstance::*},
    test::{
      builder::TestBuilder,
      expect::{expect, ExpectedInstance},
    },
  },
  serde_json::json,
};

#[tokio::test]
async fn pinned_version_replaces_anything_different() {
  let ctx = TestBuilder::new()
    .with_package(json!({
      "name": "package-a",
      "version": "1.0.0",
      "devDependencies": {"foo": "workspace:*"}
    }))
    .with_version_group(json!({
      "dependencies": ["foo"],
      "pinVersion": "1.2.0"
    }))
    .run()
    .await;
  expect(&ctx).to_have_instances(vec![
    ExpectedInstance {
      state: InstanceState::valid(IsLocalAndValid),
      dependency_name: "package-a",
      id: "package-a in /version of package-a",
      actual: "1.0.0",
      expected: Some("1.0.0"),
      overridden: None,
    },
    ExpectedInstance {
      state: InstanceState::fixable(DiffersToPin),
      dependency_name: "foo",
      id: "foo in /devDependencies of package-a",
      actual: "workspace:*",
      expected: Some("1.2.0"),
      overridden: None,
    },
  ]);
}

Sub-module organisation

Group related scenarios under nested modules — see pinned_test.rs, catalog_defs_test.rs:

mod local {
  use super::*;
  #[tokio::test] async fn refuses_to_pin_local_version() { ... }
}

mod normal {
  use super::*;
  #[tokio::test] async fn an_already_pinned_version_is_valid() { ... }
}

mod registry_updates {
  use super::*;
  #[tokio::test] async fn def_marked_outdated_when_registry_has_newer_version() { ... }
}

File location

Test type	Location
Version-group behaviour (pin, ban, ranges …)	src/version_group/<group>_test.rs
Catalog discovery wiring	src/version_group/{catalog,bun_catalog}_test.rs
Fix mutations	src/commands/fix_test.rs
Format pass	src/visit_formatting/format_test.rs
Other unit tests	Co-located: src/foo.rs ↔ src/foo_test.rs

Builder methods

Source of truth: src/test/builder.rs.

Method	Purpose
.with_package(json!({...}))	Add one package.json
.with_packages(vec![...])	Add many
.with_version_group(json!({...}))	Add one version group
.with_version_groups(vec![...])	Add many
.with_semver_group(json!({...}))	Add a semver group
.with_config(json!({...}))	Base config (e.g. customTypes, dependencyGroups)
.with_strict(bool)	Strict mode (Suspect → error)
.with_subcommand("update")	Override subcommand (default: lint, or update if registry set)
.with_pnpm_catalogs(yaml)	Inject pnpm-workspace.yaml; implies pnpm PM
.with_bun_catalogs(json!({...}))	Synthetic Bun root with /catalog, /catalogs/{n}; implies Bun PM
.with_bun_workspaces_catalogs(json!({...}))	Same, nested under /workspaces/
.with_{pnpm,bun,npm,yarn,unknown}_package_manager()	Force PM detection
.with_registry_updates(json!({"react":[...]}))	Mock npm registry; implies subcommand=update
.with_update_target(UpdateTarget::Minor)	Bound update target
.run().await → Context	Primary end-to-end (full pipeline through disk + discovery)
.build()	Sync, no visit — context-wiring tests
.build_and_visit_packages()	Sync + visit_packages — fix tests, older suites
.build_and_visit_formatting()	Sync + visit_formatting
.build_with_registry_and_visit().await	Sync wiring + async registry mock + visit

ExpectedInstance fields

ExpectedInstance {
  state: InstanceState::fixable(DiffersToPin),  // valid / fixable / unfixable / suspect
  dependency_name: "react",                     // = `internal_name` (alias-aware)
  id: "react in /dependencies of package-a",    // {dep} in {/path} of {package_or_yaml}
  actual: "17.0.0",                             // raw specifier on disk
  expected: Some("18.0.0"),                     // None = ignore; Some("") = remove
  overridden: None,                             // semver-group override target, if any
}

id location examples:

• /dependencies, /devDependencies, /peerDependencies
• /version of package-a (local version)
• /packageManager, /engines/node
• /catalog of pnpm-workspace.yaml, /catalogs/<name> of pnpm-workspace.yaml
• /customVersion, /custom/config/version (via customTypes)

Patterns

→ patterns.md: banned, pinned, sameRange, pnpm catalogs, bun catalogs, semver ranges, registry updates.

Fix tests

src/commands/fix_test.rs builds with .build_and_visit_packages() then runs fix::run(ctx, &SilentReporter, &disk). dry_run = true is the default (set by mock::config_from_mock), so is_dirty() and post-fix contents stay observable. Set ctx.config.cli.dry_run = false only when asserting writes through a recording MockDiskIo (see pnpm_fix_writes_yaml_to_disk).

Common mistakes

Wrong	Right
#[test] fn foo() + .run().await	#[tokio::test] async fn foo()
use crate::instance_state::*	use crate::instance::*
"pinned": "1.0.0"	"pinVersion": "1.0.0"
Context { ... }	TestBuilder::new()...
ctx.instances[0]	expect(&ctx).to_have_instances(vec![...])
.build() then check states	.run().await (or .build_and_visit_packages() for sync)
Missing SuspectInstance::* import	Import all 4: FixableInstance::*, ValidInstance::*, SuspectInstance::*, UnfixableInstance::*

Running

just test                            # all
cargo test pinned_test               # pattern match
cargo test test_name -- --nocapture  # with stdout

Reference tests

• src/version_group/banned_test.rs — banned + custom types
• src/version_group/pinned_test.rs — sub-modules, semver-group interaction
• src/version_group/same_range_test.rs — range satisfaction
• src/version_group/catalog_test.rs — pnpm catalogs
• src/version_group/bun_catalog_test.rs — bun catalogs (sync .build())
• src/version_group/preferred_semver_test.rs — registry updates, update targets