Add --update-expected-output (#492)

Author: DanielNoord

pydocstringformatter/_testutils/__init__.py

@@ -17,6 +17,8 @@
 
 LOGGER = logging.getLogger(__name__)
 
+UPDATE_OUTPUT_OPTION = "--update-expected-output"
+
 
 class FormatterAsserter(contextlib.AbstractContextManager):  # type: ignore[type-arg]
     """ContextManager used to assert that a Formatter does something on a docstring.
@@ -84,4 +86,10 @@ def __exit__(
         return None
 
 
-__all__ = ["FormatterAsserter", "MakeAFormatter", "MakeBFormatter", "AddBFormatter"]
+__all__ = [
+    "FormatterAsserter",
+    "MakeAFormatter",
+    "MakeBFormatter",
+    "AddBFormatter",
+    "UPDATE_OUTPUT_OPTION",
+]

tests/conftest.py

@@ -2,6 +2,8 @@
 
 import pytest
 
+from pydocstringformatter._testutils import UPDATE_OUTPUT_OPTION
+
 
 @pytest.fixture
 def test_file(tmp_path: Path) -> str:
@@ -10,3 +12,14 @@ def test_file(tmp_path: Path) -> str:
     with open(filename, "w", encoding="utf-8") as file:
         file.write('"""A multi-line\ndocstring."""')
     return str(filename)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Add command line options to pytest."""
+    parser.addoption(
+        UPDATE_OUTPUT_OPTION,
+        action="store_true",
+        help="Update the expected output for tests. This will overwrite the output "
+        "files to be as the tests are currently producing them.",
+        default=False,
+    )

tests/test_formatting.py

@@ -7,6 +7,7 @@
 import pytest
 
 import pydocstringformatter
+from pydocstringformatter._testutils import UPDATE_OUTPUT_OPTION
 
 HERE = Path(__file__)
 TEST_DATA = HERE.parent / "data" / "format"
@@ -28,7 +29,10 @@
     ids=TEST_NAMES,
 )
 def test_formatting(
-    test_file: str, capsys: pytest.CaptureFixture[str], tmp_path: pathlib.Path
+    test_file: str,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: pathlib.Path,
+    request: pytest.FixtureRequest,
 ) -> None:
     """Test that we correctly format all files in the format directory.
 
@@ -76,7 +80,23 @@ def test_formatting(
         [temp_file_name, "--write"] + additional_args
     )
 
-    output = capsys.readouterr()
-    assert output.err == error_message.format(testfile=os.path.abspath(temp_file_name))
+    error_output = capsys.readouterr()
+    assert error_output.err == error_message.format(
+        testfile=os.path.abspath(temp_file_name)
+    )
     with open(temp_file_name, "rb") as f:
-        assert f.read() == expected_output
+        output = f.read()
+        try:
+            assert output.decode("utf-8") == expected_output.decode("utf-8")
+        except AssertionError as e:  # pragma: no cover
+            if request.config.getoption(UPDATE_OUTPUT_OPTION):
+                with open(test_name, "wb") as fw:
+                    fw.write(output)
+                pytest.fail(
+                    "Updated expected output. Please check the changes and commit them."
+                )
+
+            raise AssertionError(
+                f"Output of '{Path(test_file).stem}' does not match expected output. "
+                f"Run with '{UPDATE_OUTPUT_OPTION}' to update the expected output."
+            ) from e