From aeb15844e3fda2bd3bcfc0cc2764dd75b7ed473e Mon Sep 17 00:00:00 2001 From: Fazeel Usmani Date: Tue, 11 Nov 2025 12:30:14 +0000 Subject: [PATCH 1/2] =?UTF-8?q?Add=20online=20CLI=20options=20reference=20?= =?UTF-8?q?=E2=80=93=20fixes=20#4492?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/en/how-to/cli-options.rst | 307 ++++++++++++++++++++++++++++++++++ doc/en/how-to/index.rst | 1 + 2 files changed, 308 insertions(+) create mode 100644 doc/en/how-to/cli-options.rst diff --git a/doc/en/how-to/cli-options.rst b/doc/en/how-to/cli-options.rst new file mode 100644 index 00000000000..8c0a3b33a90 --- /dev/null +++ b/doc/en/how-to/cli-options.rst @@ -0,0 +1,307 @@ +.. _cli-options: + +Command-line Options Reference +================================ + +Pytest provides numerous command-line options for controlling test discovery, execution, +reporting, configuration, and debugging. This reference covers the most commonly used +options, organized by functionality. + +For a complete list of all available options, run: + +.. code-block:: bash + + pytest --help + +Or see the :ref:`complete command-line flag reference `. + + +Running and Selecting Tests +---------------------------- + +**Run tests by keyword expression** + +The ``-k`` option lets you run tests matching a substring expression: + +.. code-block:: bash + + pytest -k "expression" + pytest -k "MyClass and not method" + +This runs tests whose names match the given expression (case-insensitive). You can use +Python operators like ``and``, ``or``, and ``not``. + +**Run tests by marker** + +The ``-m`` option runs tests decorated with specific markers: + +.. code-block:: bash + + pytest -m slow + pytest -m "not slow" + pytest -m "mark1 and not mark2" + +See :ref:`marks ` for more information on using markers. + +**Exit on first failure** + +.. code-block:: bash + + pytest -x # Exit on first failure + pytest --exitfirst # Same as -x + pytest --maxfail=2 # Exit after 2 failures + +The ``-x`` / ``--exitfirst`` option stops the test run immediately on the first failure, +while ``--maxfail`` lets you specify how many failures to tolerate before stopping. + +**Run previously failed tests** + +.. code-block:: bash + + pytest --lf # Run only last failed tests + pytest --last-failed # Same as --lf + pytest --ff # Run all tests, but failures first + pytest --failed-first # Same as --ff + +These options use pytest's cache to rerun failed tests, useful for quickly iterating +on fixes. See :ref:`cache ` for more information. + +**Stepwise execution** + +.. code-block:: bash + + pytest --sw # Stop at first failure, continue from there next run + pytest --stepwise # Same as --sw + +Stepwise mode stops at the first failure and continues from that test on the next run. + + +Output and Verbosity +-------------------- + +**Control verbosity** + +.. code-block:: bash + + pytest -v # Increase verbosity (show individual test names) + pytest -vv # Even more verbose + pytest -q # Decrease verbosity (quiet mode) + pytest -qq # Even quieter + pytest --verbose # Same as -v + pytest --quiet # Same as -q + +The ``-v`` option shows more detail about test execution, while ``-q`` reduces output. + +**Traceback formatting** + +.. code-block:: bash + + pytest --tb=auto # Default: intelligent traceback formatting + pytest --tb=short # Shorter traceback format + pytest --tb=long # Longer traceback format + pytest --tb=line # Only the failing line + pytest --tb=native # Python's standard traceback + pytest --tb=no # No traceback + +The ``--tb`` option controls how tracebacks are displayed for failed tests. + +**Show local variables** + +.. code-block:: bash + + pytest -l # Show local variables in tracebacks + pytest --showlocals # Same as -l + +This adds local variable values to the traceback output, helpful for debugging. + +**Summary information** + +.. code-block:: bash + + pytest -r fE # Show summary of failed and error tests (default) + pytest -r a # Show summary of all outcomes except passed + pytest -r A # Show summary of all outcomes + pytest -r f # Show only failed + pytest -r fEsx # Show failed, errors, skipped, xfailed + +The ``-r`` option controls what appears in the test summary at the end of the run. + +**Disable header and summary** + +.. code-block:: bash + + pytest --no-header # Don't show the header + pytest --no-summary # Don't show the summary + + +Reporting and Output Files +--------------------------- + +**JUnit XML reports** + +.. code-block:: bash + + pytest --junit-xml=path/to/report.xml + pytest --junit-prefix=myproject + +Generate JUnit-style XML reports, useful for CI/CD integration. + +**Duration reporting** + +.. code-block:: bash + + pytest --durations=10 # Show 10 slowest tests + pytest --durations=0 # Show all durations + pytest --durations=5 --durations-min=1.0 # Show 5 slowest tests over 1 second + +See :ref:`durations ` for more details. + +**Control output capture** + +.. code-block:: bash + + pytest -s # Disable output capturing + pytest --capture=no # Same as -s + pytest --capture=fd # Capture at file descriptor level (default) + pytest --capture=sys # Capture at sys level + +By default, pytest captures stdout/stderr. Use ``-s`` to see output in real-time. + + +Collection and Test Discovery +------------------------------ + +**Collect without running** + +.. code-block:: bash + + pytest --collect-only # Show which tests would be collected + pytest --co # Same as --collect-only + +Useful for verifying test discovery without running tests. + +**Import Python packages** + +.. code-block:: bash + + pytest --pyargs pkg.testing + +Import packages and run tests from their filesystem location. + +**Ignore paths** + +.. code-block:: bash + + pytest --ignore=path/to/ignore + pytest --ignore-glob=**/old_*.py + +Exclude specific paths or patterns from test collection. + +**Configure conftest loading** + +.. code-block:: bash + + pytest --confcutdir=dir # Only load conftest.py relative to this directory + pytest --noconftest # Don't load any conftest.py files + + +Debugging +--------- + +**Python debugger** + +.. code-block:: bash + + pytest --pdb # Drop into debugger on failures + pytest --trace # Drop into debugger at the start of each test + +**Show fixture setup** + +.. code-block:: bash + + pytest --fixtures # Show available fixtures + pytest --setup-show # Show fixture setup/teardown while running tests + pytest --setup-only # Only setup fixtures, don't run tests + + +Configuration +------------- + +**Specify config file** + +.. code-block:: bash + + pytest -c myconfig.ini # Use specific config file + pytest --config-file=pytest.ini + +**Set base temporary directory** + +.. code-block:: bash + + pytest --basetemp=dir # Base directory for temporary files + +**Override INI options** + +.. code-block:: bash + + pytest -o xfail_strict=True -o cache_dir=.custom_cache + pytest --override-ini=option=value + + +Logging +------- + +**Set log levels** + +.. code-block:: bash + + pytest --log-cli-level=INFO # Set CLI logging level + pytest --log-level=DEBUG # Set capture log level + pytest --log-file=tests.log # Write logs to file + +See :ref:`logging ` for more information on pytest's logging capabilities. + + +Warnings +-------- + +**Control warning display** + +.. code-block:: bash + + pytest --disable-warnings # Disable warnings summary + pytest -W ignore::DeprecationWarning # Python warnings filter + +See :ref:`warnings ` for more information. + + +Common Option Combinations +-------------------------- + +Here are some frequently used combinations: + +.. code-block:: bash + + # Quick feedback loop - verbose, exit on first failure, show output + pytest -vsx + + # Debugging failed test - show locals, drop to debugger, verbose + pytest -lvx --pdb + + # CI/CD run - quiet, generate JUnit report, show durations + pytest -q --junit-xml=report.xml --durations=10 + + # Rerun failures with more detail + pytest --lf -vv --tb=long + + # Show what would run without executing + pytest --collect-only -q + + +See Also +-------- + +* :ref:`usage` - How to invoke pytest +* :ref:`Complete command-line flag reference ` - Full list of all flags +* :ref:`Configuration ` - Configure pytest via pytest.ini, pyproject.toml, etc. +* :ref:`Plugins ` - Extend pytest with plugins diff --git a/doc/en/how-to/index.rst b/doc/en/how-to/index.rst index 9796f1f8090..5fda4ea7a9f 100644 --- a/doc/en/how-to/index.rst +++ b/doc/en/how-to/index.rst @@ -12,6 +12,7 @@ Core pytest functionality :maxdepth: 1 usage + cli-options assert fixtures mark From bdf2ca5044f88e81b30ba8a580b24b894dddc2a6 Mon Sep 17 00:00:00 2001 From: Fazeel Usmani Date: Tue, 11 Nov 2025 13:39:56 +0000 Subject: [PATCH 2/2] Add changelog --- changelog/4492.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/4492.doc.rst diff --git a/changelog/4492.doc.rst b/changelog/4492.doc.rst new file mode 100644 index 00000000000..217db188dca --- /dev/null +++ b/changelog/4492.doc.rst @@ -0,0 +1 @@ +Added a new CLI options reference page to the documentation, organizing commonly used command-line flags by functionality for easier discovery.