ApprovalTests.Python/docs/tutorial/minimal-example.md at main

Getting Started with a Minimal Example

Steps

Steps

1. Install Dependencies

Open a terminal and run:

pip install pytest approvaltests pytest-approvaltests

2. Create the test file

Add a new file called test_with_approvals.py

containing:

from approvaltests import verify


def test_with_approvals():
    verify("Hello World")

3. Run the test

Run the test in the terminal:

python -m pytest . --approvaltests-use-reporter='PythonNativeReporter'

You should similar output to the following (paths, times, and versions might differ) :

========================================================================================================= test session starts ========================================================================================================= 
platform win32 -- Python 3.6.7, pytest-7.0.1, pluggy-1.0.0 
rootdir: C:\Code\approvaltests.minimal.example             
plugins: approvaltests-0.2.4                               
collected 1 item                                                                                                                                                                                                                        

--- test_with_approvals.test_with_approvals.approved.txt
+++ test_with_approvals.test_with_approvals.received.txt
@@ -0,0 +1 @@
+Hello World


to approve this result:

move "C:\Code\approvaltests.minimal.example\test_with_approvals.test_with_approvals.received.txt" "C:\Code\approvaltests.minimal.example\test_with_approvals.test_with_approvals.approved.txt"

======================================================================================================= short test summary info ======================================================================================================= 
FAILED test_with_approvals.py::test_with_approvals - approvaltests.approval_exception.ApprovalException: Approval Mismatch, received != approved
========================================================================================================== 1 failed in 0.53s ==========================================================================================================

Let's explore what this output means

Section 1: Run Information

========================================================================================================= test session starts ========================================================================================================= 
platform win32 -- Python 3.6.7, pytest-7.0.1, pluggy-1.0.0 
rootdir: C:\Code\approvaltests.minimal.example             
plugins: approvaltests-0.2.4                               
collected 1 item

This section states what is being run. Which tools and with directories, it also states that pytest found 1 item meaning 1 test was run.

Section 2: ApprovalTests diff report

--- test_with_approvals.test_with_approvals.approved.txt
+++ test_with_approvals.test_with_approvals.received.txt
@@ -0,0 +1 @@
+Hello World

This is the result of the verify("Hello World") call. It has failed, and there it reports the difference between this run ("received") and what it was expecting ("approved"). The approved version is saved in the test_with_approvals.test_with_approvals.approved.txt file. Which is current empty, because this is the first time the test has ever been run and the results has never been approved.

The current results of what was passed to the verify method have been saved to the "received" file: test_with_approvals.test_with_approvals.received.txt

The difference (diff) is being displayed with the pluses and minuses. All the changes have a + next to them showing that all the changes are added lines.

Section 3: How to approve the new result

to approve this result:

move "C:\Code\approvaltests.minimal.example\test_with_approvals.test_with_approvals.received.txt" "C:\Code\approvaltests.minimal.example\test_with_approvals.test_with_approvals.approved.txt"

Once you are seeing the results you want, to "approve" them they must be copied into the .approved.` file. One way to do this is via the command line. The exact command needed for your os will appear here. Copy, paste, and run the command to "approve" the result. Doing this should make the test pass the next time it is run.

Section 4: Summary

======================================================================================================= short test summary info ======================================================================================================= 
FAILED test_with_approvals.py::test_with_approvals - approvaltests.approval_exception.ApprovalException: Approval Mismatch, received != approved
========================================================================================================== 1 failed in 0.53s ==========================================================================================================

The above summarizes the results of all (1) of the tests run in the session.

4. Approve the results

Copy the .received. to the .approved.

Unix

mv -f "test_with_approvals.test_with_approvals.received.txt" "test_with_approvals.test_with_approvals.approved.txt"

Windows

move "test_with_approvals.test_with_approvals.received.txt" "test_with_approvals.test_with_approvals.approved.txt"

5. Rerun the tests