expecttest

library0.3.0pypypi✓ verified 24d ago

Expecttest is a Python library that implements 'expect tests' (also known as 'golden tests' or 'snapshot tests'). Unlike traditional asserts, it automatically populates the expected output of a test. When the test output changes, the library facilitates updating the expected output directly within the Python source file by modifying it in-place. The current version is 0.3.0, released in December 2024, indicating active development with a fairly rapid release cadence.

testing

pip install expecttest

github ↗package ↗

INSTALL

IMPORT

SIG · EXPECTTEST

expecttest

testingpythonv0.3.0

Install

1.7s avg

Import

141ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.158s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.124s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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).

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()

Debug

Known issues

breakingThe 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.

affects: All versions

gotchaTests 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.

affects: All versions

gotchaThe 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.

affects: All versions

gotchaOver-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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'expecttest'

The 'expecttest' library is not installed in the Python environment where your code or tests are being executed, or the Python interpreter cannot find it in its search path.

fix

Install the expecttest library using pip: `pip install expecttest`

AttributeError: module 'expecttest' has no attribute 'ACCEPT'

Developers often mistake `EXPECTTEST_ACCEPT` for a module attribute, but it is an environment variable that needs to be set before running tests to accept new expected outputs.

fix

Instead of accessing it as `expecttest.ACCEPT`, set the environment variable before running your tests: `EXPECTTEST_ACCEPT=1 pytest` (for pytest) or `EXPECTTEST_ACCEPT=1 python your_test_file.py`.

Tests failing (expectations differ), requiring EXPECTTEST_ACCEPT=1

The actual output of your test no longer matches the previously recorded expected value in your source code. This is the intended behavior of expecttest to highlight changes.

fix

If the change is intentional and the new output is correct, re-run your tests with the `EXPECTTEST_ACCEPT=1` environment variable to update the expected values in your source files: `EXPECTTEST_ACCEPT=1 pytest` or `EXPECTTEST_ACCEPT=1 python your_test_file.py`. Always review the resulting diffs.

AssertionError: Failed to substitute string

This error occurs when the expecttest library encounters an issue while trying to modify the source file to update an expected string, potentially due to complex string patterns, file access issues, or an internal parsing problem.

fix

Simplify the content of the expected string or the surrounding code if possible. Ensure the test file is writable. If the problem persists, check for updates to the expecttest library as it might be a bug in older versions.

Upgrade

Version history

0.3.0latest on PyPI · released Dec 11, 2024

Audit

Dependencies

pythonrequiredRequired runtime environment.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/ezyang/expecttest ↗

packagehttps://pypi.org/project/expecttest/ ↗