ApprovalTests

Common errors

• ModuleNotFoundError: No module named 'approvaltests'

  cause If this occurs after `pip install approvaltests`, it's likely due to a packaging error in version 17.4.2.
  fix Upgrade to the latest version: `pip install --upgrade approvaltests` (to get 17.4.3 or newer).

• No reporter found for file: your_test_name.received.txt

  cause ApprovalTests could not find or launch a suitable diff tool to display the comparison between the received and approved files.
  fix Install a supported diff tool (e.g., Beyond Compare, Meld, VS Code) and ensure it's configured correctly according to the ApprovalTests documentation (e.g., in your PATH or via `reporters.json`).

• ImportError: cannot import name 'BeyondCompareReporter' from 'approvaltests.reporters'

  cause You are attempting to import a reporter class using an old path or name that was changed in v17.0.0.
  fix Update your import statement and reporter usage. For Beyond Compare, use `from approvaltests.reporters.diff_reporters.report_with_beyond_compare import ReportWithBeyondCompare` and pass it to `Options().with_reporters(...)`.

Warnings

• breaking Prior to v17.0.0, diff reporters were configured differently, often relying on `reporters.json` or direct imports of reporter classes that no longer exist or have been renamed. This can lead to `ImportError` or unexpected reporter behavior when upgrading.
  Fix: Update reporter imports to use the `ReportWith...` pattern (e.g., `options=Options().with_reporters(ReportWithBeyondCompare)`). Consult the official documentation for the latest reporter names and configuration methods. The `reporters.json` file is still supported for customization but not for built-in reporter definitions.
• gotcha ApprovalTests relies on external diff tools (like Beyond Compare, Meld, KDiff3, VS Code diff) to compare received and approved files. If no diff tool is detected or configured, approval tests might not open a comparison window, or fail with a 'no reporter found' message, potentially leading to unnoticed changes or manual file comparison.
  Fix: Ensure a diff tool is installed on your system and configured for ApprovalTests. This often involves ensuring the tool is in your system's PATH, setting environment variables, or creating a `reporters.json` file. Check the 'Reporters' section of the ApprovalTests documentation for setup instructions.
• breaking Version 17.4.2 had a packaging error that prevented it from being imported, leading to an `ImportError` or `ModuleNotFoundError` immediately after installation, making the library unusable.
  Fix: Upgrade to version 17.4.3 or later: `pip install --upgrade approvaltests`. This issue was resolved in the subsequent patch release.

Install

• pip install approvaltests Install latest version

Imports

• verify

  from approvaltests import verify

• Options

  from approvaltests import Options

• ReportWithBeyondCompare
  wrong:

  from approvaltests.reporters import BeyondCompareReporter

  correct:

  from approvaltests.reporters.diff_reporters.report_with_beyond_compare import ReportWithBeyondCompare

  Reporter names changed significantly in v17.0.0.

Quickstart

This quickstart demonstrates a basic approval test. Running this code will create a `.received.txt` file with the generated content and, if configured, open an external diff tool (like Beyond Compare or Meld) to compare it against a `.approved.txt` file. On the first run, you'll need to approve the `.received` content, usually by copying it to the `.approved` file via the diff tool. Subsequent runs will pass if the content has not changed.

from approvaltests import verify, Options

def generate_report_content():
    return (
        "User Report:\n" 
        "- ID: 123\n" 
        "- Name: Alice Wonderland\n" 
        "- Email: alice@example.com\n"
    )

# This will generate a .received.txt file and attempt to open a diff tool.
# The first run will likely show a diff, subsequent runs pass if content matches.
verify(generate_report_content())