ApprovalTests.Python

The ApprovalTests.Python documentation is organized into several sections to help you master approval testing:

• How to: Practical guides for specific tasks like selecting reporters, creating custom verify() methods, testing binary data, scrubbing dates, and handling multiple approvals per test.
• Reference: Technical details on configuration options, Storyboard, MarkdownTables, and the SimpleLogger.
• Explanations: Conceptual deep-dives into what approvals are, the benefits of different reporters, and the theory behind approval testing.
• Tutorial: A guided introduction to understanding and using reporters.

The repository uses a standardized set of development scripts to provide a consistent interface for common tasks across different platforms. These scripts are designed to be extremely short, delegating the actual work to Mise tasks.

Commonly available scripts include:

• build_and_test: Runs the full build pipeline, including tests and linting. This is the primary script used by CI.
• tidy_code: Formats code and applies automatic fixes (e.g., removing unused imports).
• update_docs: Updates markdown documentation with code snippets.
• run: Executes the project (for non-library projects), building as necessary.

The .failed_comparison.log file records every failed approval comparison. Each line follows the format: <received_file> -> <approved_file>.

Use Case: This log allows you to perform batch approvals of all current failures using the approve_all.py utility script.

Approvals verify test results by comparing them against a "golden master" (an approved snapshot).

1. First Run: If no golden master exists, ApprovalTests creates a snapshot of the current results and uses it as the golden master.
2. Subsequent Runs: The library compares the new results against the golden master.
3. Failure: If the results differ, a Reporter launches an external diff utility to show the differences.
4. Resolution: You can either update the golden master (if the change was expected and correct) or revert your code changes to match the existing master.

Storyboards allow you to track an object through time by capturing multiple states (frames) in a single approval test. This is useful for visualizing workflows or the lifetime of an object. The output is formatted vertically (like a comic book) so that diff tools can clearly show the progression between frames.

To use a Storyboard manually:

1. Instantiate Storyboard().
2. Use add_description(str) to provide context for the sequence.
3. Use add_frame(content) to capture the state of your object at a specific point in time.
4. Use verify(story) to perform the approval test.

story = Storyboard()
story.add_description("Spinning wheel")
story.add_frame(ascii_wheel)
# ... perform action ...
story.add_frame(ascii_wheel)
verify(story)

Group aggregators allow users to request a tool by its family name (e.g., ReportWithBeyondCompare) regardless of their operating system or specific version.

Implementation Steps:

1. Identify rows sharing the same non-empty group_name.
2. Convert group_name from SCREAMING_SNAKE_CASE to PascalCase.
3. Create a FirstWorkingReporter subclass named ReportWith{GroupPascalCase}.
4. Include all reporters in that group in the order they appear in the CSV.
5. Note: No OS-specific guard is required for group reporters, as individual reporter classes will fail gracefully if their executable is not found on the current system.

Example: ReportWithBeyondCompare might try ReportWithBeyondCompareMac, ReportWithBeyondCompare3Windows, and ReportWithBeyondCompare4Windows in sequence.

Custom scrubbers registered via DateScrubber.add_scrubber are automatically included in the scrubbing process whenever get_scrubber_for() is called.

If you need to remove all registered custom scrubbers, you can call DateScrubber._clear_custom_scrubbers().

The toString() method of FirstWorkingReporter provides a human-readable representation of the reporter instance. This is useful for debugging, logging, and equality comparisons. The implementation works by recursively calling the toString() method of each individual reporter contained within the FirstWorkingReporter instance to build a composite string representation.

"FirstWorkingReporter(ReporterForTesting(True), ReporterForTesting(False))"