mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
[Português](TESTING.pt-BR.md)

# Testing


## Running the suite
- Run `cargo test` at the repository root for the whole suite
- Run `cargo test --test <NAME>` for one proof binary
- Run `cargo build` first if you want compilation errors reported separately
- Run `rg -c '#\[test\]' src/ tests/` to count the proofs yourself
- The count is NOT published here, because a number in prose is a claim nothing checks
- It was published once, said 1375, and had drifted by the time somebody counted
- A proof binary is a separate crate, compiled and run on its own
### The other two gates
- Run `cargo clippy --all-targets` for the linter
- `pedantic = "deny"` is stated in `Cargo.toml`, so a pedantic warning fails the build
- The rule covers every target, not the library alone
- An item-level `#[allow]` still wins, with the reason written beside the code
- Run `cargo doc --no-deps --all-features` for the documentation build
- `broken_intra_doc_links` and `invalid_codeblock_attributes` are denied
- Neither `cargo build` nor `cargo test` ever evaluates those two rules
- SO RUN ALL THREE, BECAUSE A GREEN SUITE PROVES ONLY ONE OF THEM
### What the invocation proof does NOT cover
- One proof runs every invocation the published documents show through the parser
- It proves the argument layer accepts them, and it proves nothing beyond that
- A command validates its own arguments AFTER the parser and BEFORE the server
- An invocation can pass the parser and be refused by the command it named
- `data export --table t --output f` was exactly that, and it was published for months
- `--output` is global, so it parsed, and the command wanted `--to` instead
- `--print-schema` exits before that validation, so it cannot catch it either
- SO A GREEN INVOCATION PROOF IS NOT PROOF THAT A RECIPE WORKS
- Closing this needs a live server, which is the boundary this suite does not cross


## Build and test are always local
- Every gate runs on the machine where the work was done
- BUILD LOCALLY, ALWAYS
- TEST LOCALLY, ALWAYS
- NEVER build this product on a remote host
- NEVER run this suite on a remote host
- A gate that runs somewhere else is a gate somebody else has to read
- The result you did not watch is a result you cannot answer for


## Proofs that need a server
- Part of the suite reaches a real MariaDB server
- Those proofs read a destination from a local file
- The file is `tests/destination.toml`
- It names a real server, a real account and a real password
- It carries one of each for the three privilege levels the suite exercises
- IT IS NEVER PUBLISHED AND NEVER COMMITTED
- It is listed in `.gitignore`, so it is absent from history
- The manifest `include` list omits it, so it is absent from the archive
- The two guards answer different questions
- `include` decides what a stranger downloads
- `.gitignore` decides what a stranger can read after the fact
### The material beside it
- `tests/*.pem` holds the client identity and trust anchors for the encrypted channel
- The private key is the credential itself
- Those files are generated locally against a local authority
- They are ignored by the same rule and for the same reason
### Proofs that need no server
- The rest of the suite runs anywhere, with no destination file present
- Those are the proofs that exercise argument handling, refusals and output shaping
- A missing destination file skips the server proofs rather than failing them


## Contract proofs read the requirements document
- The full contract is working material and is not published with the crate
- It is the specification, not a summary of the code
- Some proofs read that document with `include_str!` and compare it against the product
- `tests/published_contract.rs` reads it
- `tests/published_argv.rs` reads it
- `tests/requirement_coverage.rs` reads it
- `tests/requirement_execution.rs` reads it
- `tests/global_flags.rs` reads it
- They refuse to pass unless every requirement stated is cited by something that runs
- SO DRIFT BETWEEN DOCUMENT AND PRODUCT FAILS THE SUITE
- Editing the document without editing the product fails
- Editing the product without editing the document fails
- The document travels inside the published archive for exactly this reason
- Shipping the proofs without the document they read would break the crate's own tests


## The implementer does not approve their own work
- Whoever wrote the change does not decide that the change is done
- A green suite is evidence, not approval
- SEPARATE THE PERSON WHO IMPLEMENTS FROM THE PERSON WHO APPROVES
- NEVER sign off on your own delivery
- An author reads their own work as they meant it, not as it is
- The gate exists to catch what the author cannot see by definition
- Report what passed, what failed and what was not measured
- NEVER report a step as verified when it was skipped