dir_spec
Star
Fork
Watch
dir_spec docs dev testing.md
2.5 kB · 62 lines
Markdown
at main

Testing #

This guide covers how to write and organize tests in Gest.

The goal is to test meaningful behavior without over-testing trivial code. When in doubt, focus on logic that could break -- transformations, edge cases, and complex calculations.

Core Principle #

Tests are the source of truth. Tests define the expected behavior of the system. If a test passes, the behavior it describes is correct by definition.

Never modify existing integration tests unless the issue explicitly calls for behavioral change. If an integration test is failing, the implementation needs to change -- not the test. The only exception is when the issue or spec explicitly requires a change in observable behavior.

Running Tests #

mise run test                        # Run all tests
mise run test -- --test xyz          # Run tests matching "xyz"

What to Test #

Test:

  • Functions and methods with logic (arithmetic, transformations, conditionals)
  • Display/formatting implementations
  • Custom comparison or ordering implementations
  • Edge cases and boundary conditions
  • Inverse operations (roundtrip tests)
  • Error paths and failure modes

Skip:

  • Simple constructors that just assign fields
  • Trivial getters that return field values
  • Thin wrappers that only delegate to another function

Before writing a test, ask: "Does this test verify actual logic, or just that field assignment works?"

Test Structure #

Tests should be organized in a way that mirrors the module structure. Group tests by the function or method they exercise, and name test functions descriptively using the pattern it_<does_something>.

Conventions #

Naming: Test functions use the pattern it_<does_something>. Group names match the function or method being tested.

Ordering: Test groups follow code style ordering -- static/associated functions first (alphabetically), then instance methods (alphabetically).

Test body structure: Separate setup from assertions with a blank line. For tests with multiple assertion groups, separate each group with a blank line.

Integration tests: Integration tests validate end-to-end behavior and are the strondir_spec contract in the codebase. They must not be modified to make a failing implementation pass. If an integration test fails after a code change, the code change is wrong unless the issue explicitly calls for a behavioral change.