In this article, you will learn the uses of the various Pytest command-line arguments.  The arguments are used to alter the default way that Pytest runs finds and executes tests.

This article assumes that you have Python and Pytest installed, and that you can use your computer's computer interface to run basic commands. 

To run all the tests in a given directory, you can run the pytest command without any argument.

If called without a file arguments as in above, Pytest will search the current directory for all test files and will run the tests.

pytest

You can also explicitly specify the exact files, and Pytest will only run those files.

pytest    path/to/test_file1.py    path/to/test_file2.py   ...

For demonstration purposes I have a directory called demo,  with a test files called test_file.py.

demo
└─ test_file2.py

Let us put some test functions in the two test files.

#test_file.py

import math

def test_sqrt():
   num = 25
   assert math.sqrt(num) == 5 #pass

def testsquare():
   num = 3
   assert num * num == 12 #fail

def testPower():
   assert math.pow(5, 3) == 125 #pass

To run the test in test_file.py. We run the following Pytest Command:

pytest    demo/test_file.py 

And we get the following output:

demo\test_file.py .F.                                                                                            [100%]

====================================================== FAILURES =======================================================
_____________________________________________________ testsquare ______________________________________________________

    def testsquare():
       num = 3
>      assert num * num == 12 #fail
E      assert (3 * 3) == 12

demo\test_file.py:11: AssertionError
=============================================== short test summary info ===============================================
FAILED demo/test_file.py::testsquare - assert (3 * 3) == 12
============================================= 1 failed, 2 passed in 0.75s =============================================

As you can see above, the test report indicates that 2 tests passed and 1 failed. 

Now let us move to what brought us here. The first command-line argument we will look at is the -v argument. The -v argument is used to increase the verbosity of the test report. 

pytest    demo/test_file.py    -v

As shown above, the arguments are entered at the end of the pytest command, normally with a leading hyphen (-) and in some cases double hyphens(--) as we will see in a while. If you run the above command the test report will be more detailed as shown below.

collected 3 items

demo/test_file.py::test_sqrt PASSED                                                                              [ 33%]
demo/test_file.py::testsquare FAILED                                                                             [ 66%]
demo/test_file.py::testPower PASSED                                                                              [100%]

====================================================== FAILURES =======================================================
_____________________________________________________ testsquare ______________________________________________________

    def testsquare():
       num = 3
>      assert num * num == 12 #fail
E      assert (3 * 3) == 12

demo\test_file.py:11: AssertionError
=============================================== short test summary info ===============================================
FAILED demo/test_file.py::testsquare - assert (3 * 3) == 12
============================================= 1 failed, 2 passed in 0.32s =============================================

Some arguments have both a short form and a long form. In the short form, we normally use a leading single hyphen while in the long form we use double hyphens. For example, the long form of the -v command is  --verbose, which means that we can also run this command as shown below:

pytest    demo/test_file.py    --verbose

The output will be just the same, as shown below. 

demo/test_file.py::test_sqrt PASSED                                                                              [ 33%]
demo/test_file.py::testsquare FAILED                                                                             [ 66%]
demo/test_file.py::testPower PASSED                                                                              [100%]

====================================================== FAILURES =======================================================
_____________________________________________________ testsquare ______________________________________________________

    def testsquare():
       num = 3
>      assert num * num == 12 #fail
E      assert (3 * 3) == 12

demo\test_file.py:11: AssertionError
=============================================== short test summary info ===============================================
FAILED demo/test_file.py::testsquare - assert (3 * 3) == 12
============================================= 1 failed, 2 passed in 0.30s =============================================

Another common command, which ideally is the one we should have started with is the -V command and its longer form --version. This command simply displays the version of Pytest that is running.

pytest    -V 
   or
pytest    --version

The output will be as shown below:

pytest 8.3.3

Pytest Arguments CheatSheet

short form long form purpose
  --collect-only Shows the tests that will be executed with the given command without actually running them.
-k EXPRESSION   Lets you use an expression to specify what test functions to run.
-x --exitfirst Stops the entire test session when a single test fails.
  --maxfail=n Specifies how many tests should be allowed to fail. Pytest will not execute any other test if n is reached.
-s --capture=no Allows print statements to actually be displayed to stdout while the tests are running
--lf --last-failed Makes pytest to execute only those tests that failed in the previous run.
--ff --failed-first Makes pytest to run the tests that failed in the previous run, before the tests that passed.
-v --verbose Increases verbosity. The test report is more detailed with --verbose set than otherwise.
-q --quiet The opposite of --verbose. It minimizes the details in the test report.
-l --showlocals If set, local variables and their values are displayed with tracebacks for failing tests
--tb=style   Modifies the way tracebacks for failures are output. Some common styles are short, line and no.
  --durations=n Reports the slowest n number of tests after the tests are run. If --durations=0, it reports everything in order of slowest to fastest.
-V --version Displays the current version of Pytest and where it is installed.
-h --help Displays helpful message, on the usage the pytest command as well as the command-line arguments 

The above usage explanations are quite easy to understand, however, you should use the arguments more and more to understand better what each does. You can also combine multiple arguments to further control the test behavior. As shown below:

pytest    demo/test_file.py    -x    --quiet

If you run the above command, you will get the following output.

.F
====================================================== FAILURES =======================================================
_____________________________________________________ testsquare ______________________________________________________

    def testsquare():
       num = 3
>      assert num * num == 12 #fail
E      assert (3 * 3) == 12

demo\test_file.py:11: AssertionError
=============================================== short test summary info ===============================================
FAILED demo/test_file.py::testsquare - assert (3 * 3) == 12
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! stopping after 1 failures !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1 failed, 1 passed in 0.30s