Expecttest

Warnings

• breaking The primary mechanism of `expecttest` involves directly modifying your source code files when `EXPECTTEST_ACCEPT=1` is set. This is a deliberate feature, but it means test runs can alter committed files, requiring careful use and potentially source control review of changes.
  Fix: Be aware of when and how `EXPECTTEST_ACCEPT=1` is used. Always review the generated diffs before committing any changes made by `expecttest` to ensure they reflect intended behavior changes, not unintended regressions.
• gotcha Tests using `expecttest` will fail if the actual output differs from the stored expected value, even if the change is valid (e.g., due to a new feature). You must explicitly run tests with `EXPECTTEST_ACCEPT=1` to update the expected values in the source code.
  Fix: Always run `EXPECTTEST_ACCEPT=1` only when you intend to accept new output as the correct expectation. Treat the resulting diffs in your source code as a change to be reviewed, similar to any other code modification.
• gotcha The effectiveness of `expecttest` heavily relies on designing the output format of your test results. Poorly structured or verbose output can lead to 'spurious changes' (e.g., minor whitespace variations, irrelevant details) that frequently cause tests to fail and require re-acceptance, diminishing their value.
  Fix: When creating functions to be tested with `expecttest`, consider implementing custom pretty-printers or helper functions to produce concise, stable, and readable output that focuses only on the essential aspects being tested.
• gotcha Over-reliance on `EXPECTTEST_ACCEPT=1` without thorough review of the updated expected values can lead to 'locking in' an implementation rather than verifying desired behavior, potentially masking bugs.
  Fix: Treat the auto-generated expected output as part of the test specification. Always review the diffs created by `EXPECTTEST_ACCEPT=1` to ensure the new expected behavior is indeed correct and intentional, not merely accepting unintended changes.

Install

• pip install expecttest Install latest version

Imports

• TestCase

  from expecttest import TestCase

  For integration with `unittest.TestCase`.
• assert_expected_inline

  from expecttest import assert_expected_inline

  For direct use in non-unittest test functions (e.g., Pytest).

Quickstart

To use `expecttest`, define your test using `TestCase` (for `unittest`) or directly call `assert_expected_inline` (for Pytest or standalone). Initially, provide an empty triple-quoted string as the expected value. Run your tests normally; they will fail if the expected string is empty or differs. To automatically populate or update the expected string in your source file, run your tests with the `EXPECTTEST_ACCEPT=1` environment variable set. This modifies your Python file directly.

import unittest
import os
from expecttest import TestCase, assert_expected_inline

# Example for unittest integration
class TestMyFunction(TestCase):
    def test_basic_output(self):
        result = f"Hello, {1 + 2}!\nMultiline output." # Simulate some function output
        # On first run, leave expected blank. Run with EXPECTTEST_ACCEPT=1 to populate.
        # self.assertExpectedInline(result, """)"""
        self.assertExpectedInline(result, """Hello, 3!\nMultiline output.""")

# Example for pytest or general use
def test_another_function():
    data = {'key': 'value', 'number': 123}
    result = str(data)
    # On first run, leave expected blank. Run with EXPECTTEST_ACCEPT=1 to populate.
    # assert_expected_inline(result, """)"""
    assert_expected_inline(result, """{'key': 'value', 'number': 123}""")

if __name__ == '__main__':
    # To update the expected values in the source file, run:
    # EXPECTTEST_ACCEPT=1 python your_test_file.py
    # or EXPECTTEST_ACCEPT=1 pytest your_test_file.py
    if os.environ.get('EXPECTTEST_ACCEPT') == '1':
        print("Running in ACCEPT mode. Expected values will be updated.")
    unittest.main()