Vacuous-test ratchet. Finds #test functions that construct values but contain no failure-capable operation (no assert/panic/unwrap/expect/?-propagation) — tests that pass even if the behavior they name is broken. New ones fail the build; the fix is a real assertion, never underscore-silencing.
| Tier | tools |
| Role | unclassified (baselined) |
| Path | crates/tools/test-assert-ratchet |
| Edition | 2021 |
| Targets | tools-test-assert-ratchet, tools_test_assert_ratchet, ratchet_gate |
| Public items | 16 across 0 modules |
| Tests | 17 |
What it is for
Vacuous-test ratchet.
Finds test functions that cannot fail: they construct values, call builders, coerce to trait objects — and never perform a single failure-capable operation. No assert*, no panic!, no .unwrap()/.expect(), no ? propagation, no #should_panic. Such a test is green even when the behavior it names is broken; it only proves the code compiles, which the build already proves.
The mandated fix is a real assertion on the constructed value's behavior — never an underscore binding to silence the warning, and never deleting the test without replacing the coverage intent.
Same shape as tools-security-ratchet: scan the tree, compare against a committed baseline, fail only on findings the baseline does not contain. The baseline may only shrink.
Capabilities
Baseline
Vacuous-test ratchet.
| Item |
|---|
pub struct Baseline |
Baseline :: fn load(path : & Path) -> Result <Self> |
Baseline :: fn save(& self, path : & Path) -> Result <()> |
Check
Vacuous-test ratchet.
| Item |
|---|
pub enum Check |
Check :: fn all() -> & 'static Check |
Check :: fn remedy(& self) -> & 'static str |
Check :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result |
fn check(repo_root : & Path, baseline : & Baseline) -> Result <Report> |
Finding
Vacuous-test ratchet.
| Item |
|---|
pub struct Finding |
Finding :: fn key(& self) -> String |
fn scan_source(path : & str, src : & str, out : & mut Vec <Finding>) |
fn scan(repo_root : & Path) -> Result <Vec <Finding>> |
Report
Vacuous-test ratchet.
| Item |
|---|
pub struct Report |
Report :: fn is_clean(& self) -> bool |
TestFn
Vacuous-test ratchet.
| Item |
|---|
pub struct TestFn |
fn tests_in(path : & str, src : & str) -> Vec <TestFn> |
How to use it
No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.
Module structure
No public modules: the crate root is its whole surface.
Public surface
`crate root`
| Item | What it is |
|---|---|
pub enum Check | Which class of can't-fail test a finding belongs to. |
Check :: fn all() -> & 'static Check | — |
Check :: fn remedy(& self) -> & 'static str | One line on what to do about it, printed with every new finding. |
Check :: fn fmt(& self, f : & mut fmt::Formatter <'_>) -> fmt::Result | — |
pub struct Finding | One finding |
Finding :: fn key(& self) -> String | — |
pub struct Baseline | The committed set of known-acceptable findings. |
Baseline :: fn load(path : & Path) -> Result <Self> | — |
Baseline :: fn save(& self, path : & Path) -> Result <()> | — |
pub struct Report | Result of a scan measured against a baseline. |
Report :: fn is_clean(& self) -> bool | — |
pub struct TestFn | Scan one already-cleaned source file for vacuous tests |
fn tests_in(path : & str, src : & str) -> Vec <TestFn> | Every #test in one source file, in the order they appear |
fn scan_source(path : & str, src : & str, out : & mut Vec <Finding>) | Scan a raw source file for vacuous tests. |
fn scan(repo_root : & Path) -> Result <Vec <Finding>> | Scan the tree rooted at repo_root and return every vacuous test. |
fn check(repo_root : & Path, baseline : & Baseline) -> Result <Report> | Scan and compare against the baseline. |
No pub use re-exports: every item above is declared in this crate.
Boundary
Depends on no other workspace tier.
Shares tier tools with 84 other crates: tools-advisory-reach, tools-archive-guard, tools-artifact-scaffold, tools-ask-ai-core, tools-ask-ais, tools-ask-gemini, tools-book, tools-book-report, … (84 total).
_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._
Where it sits
| Tier (ontology) | tools |
| Architectural role (taxonomy) | unclassified (baselined) |
| Location | crates/tools/test-assert-ratchet |
| Vocabulary in force (lexicon) | current |
Dependencies
Runtime, from outside the workspace.
| Crate | Requirement | Features | Optional | Only on |
|---|---|---|---|---|
anyhow | ^1 | — | no | always |
serde | ^1 | derive | no | always |
serde_json | ^1 | — | no | always |
Development. None.
Build. None.
Depended on by. 1 workspace crate.
Signal flow — what reaches this crate, and what it reaches.
flowchart LR n_tools_corpus["tools-corpus"] -->|uses| SELF SELF["tools-test-assert-ratchet"] classDef self fill:#1f883d,stroke:#1f883d,color:#fff; class SELF self;
Feature flags
No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.
Targets
| Kind | Name | Source |
|---|---|---|
| bin | tools-test-assert-ratchet | `src/main.rs` |
| lib | tools_test_assert_ratchet | `src/lib.rs` |
| test | ratchet_gate | `tests/ratchet_gate.rs` |
Error model
No public error type was detected: no public item declares a type named *Error, and no public signature returns one.
Operational characteristics
| Property | Evidence |
|---|---|
| async public surface | none detected |
| async runtime | none detected |
| database access | none detected |
| network I/O | none detected |
| unsafe code | none detected |
| environment variables | yes |
No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.
Configuration
| Variable | Read in |
|---|---|
CARGO_MANIFEST_DIR | src/main.rs |
Related capabilities
1 workspace crate depends on this one: tools-corpus.
Verification
| Kind | Count |
|---|---|
| Unit tests | 16 |
| Integration tests | 1 |
| Examples | 0 |
| Doctests | 0 |
Evidence by module. How often each public module is named by something executable.
| Module | Tests | Examples | Consumers |
|---|---|---|---|
crate root | 9 | 0 | 7 |
What the tests establish, by name:
no_new_cant_fail_tests_in_the_tree—tests/ratchet_gate.rsassert_makes_a_test_clean—src/lib.rsbare_ignore_is_flagged_reasoned_ignore_is_not—src/lib.rsclean_source_blanks_comments_strings_and_raw_strings—src/lib.rsconstruct_only_test_is_flagged—src/lib.rslifetimes_do_not_open_char_literals—src/lib.rsmultiline_signature_and_braces_in_strings_are_handled—src/lib.rsnested_helper_fn_shape_is_flagged—src/lib.rsnon_test_fns_are_ignored_even_without_asserts—src/lib.rspanic_and_matches_via_assert_are_clean—src/lib.rsresult_test_with_question_mark_is_clean_without_is_flagged—src/lib.rsshould_panic_test_is_exempt—src/lib.rsshould_panic_without_expected_is_flagged—src/lib.rssignals_inside_comments_and_strings_do_not_count—src/lib.rstautology_asserts_are_flagged—src/lib.rstokio_and_sqlx_test_attrs_are_recognized—src/lib.rsunwrap_and_expect_are_failure_signals—src/lib.rs
Documentation coverage
| Measure | Documented | Total |
|---|---|---|
| Public items with rustdoc | 10 | 16 |
Public modules with a //! block | 0 | 0 |
pie showData
title Public items with rustdoc
"Documented" : 10
"No rustdoc detected" : 6
Metrics
| Metric | Value |
|---|---|
| Rust source files | 2 |
| Source lines | 1114 |
| Code lines | 959 |
| Public API items | 16 |
| Public modules | 0 |
| Tests | 17 |
| Examples | 0 |
| Cargo features | 0 |
| Direct runtime dependencies | 3 |
| Workspace reverse dependencies | 1 |
pie showData
title Public API by kind
"enum" : 1
"function" : 4
"method" : 7
"struct" : 4
pie showData
title Rust source composition
"Code" : 959
"Blank or comment" : 155
Generation
Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.