From 6626d2aef924ecd63b53c1ddfae91ca6b99163d0 Mon Sep 17 00:00:00 2001
From: Holger Kohr <ho.kohr@zoho.com>
Date: Sat, 14 Apr 2018 10:56:13 +0200
Subject: [PATCH] Mention omission of fixtures with leading '_', closes #3398

---
 _pytest/helpconfig.py           | 3 ++-
 _pytest/python.py               | 3 ++-
 changelog/3398.trivial.rst      | 1 +
 doc/en/builtin.rst              | 2 +-
 doc/en/fixture.rst              | 6 +++---
 doc/en/getting-started.rst      | 2 ++
 doc/en/test/plugin/terminal.rst | 2 +-
 7 files changed, 12 insertions(+), 7 deletions(-)
 create mode 100644 changelog/3398.trivial.rst

diff --git a/_pytest/helpconfig.py b/_pytest/helpconfig.py
index 5a81a5bd3b8..42636bdb086 100644
--- a/_pytest/helpconfig.py
+++ b/_pytest/helpconfig.py
@@ -138,7 +138,8 @@ def showhelp(config):
     tw.line("to see available markers type: pytest --markers")
     tw.line("to see available fixtures type: pytest --fixtures")
     tw.line("(shown according to specified file_or_dir or current dir "
-            "if not specified)")
+            "if not specified; fixtures with leading '_' are only shown "
+            "with the '-v' option")
 
     for warningreport in reporter.stats.get('warnings', []):
         tw.line("warning : " + warningreport.message, red=True)
diff --git a/_pytest/python.py b/_pytest/python.py
index f9f17afd794..7444819d8b1 100644
--- a/_pytest/python.py
+++ b/_pytest/python.py
@@ -75,7 +75,8 @@ def pytest_addoption(parser):
     group = parser.getgroup("general")
     group.addoption('--fixtures', '--funcargs',
                     action="store_true", dest="showfixtures", default=False,
-                    help="show available fixtures, sorted by plugin appearance")
+                    help="show available fixtures, sorted by plugin appearance "
+                    "(fixtures with leading '_' are only shown with '-v')")
     group.addoption(
         '--fixtures-per-test',
         action="store_true",
diff --git a/changelog/3398.trivial.rst b/changelog/3398.trivial.rst
new file mode 100644
index 00000000000..a4e9ed12c3b
--- /dev/null
+++ b/changelog/3398.trivial.rst
@@ -0,0 +1 @@
+Mention in documentation and CLI help that fixtures with leading ``_`` are printed by ``pytest --fixtures`` only if the ``-v`` option is added.
diff --git a/doc/en/builtin.rst b/doc/en/builtin.rst
index 7a71827e955..506c613e5d2 100644
--- a/doc/en/builtin.rst
+++ b/doc/en/builtin.rst
@@ -12,7 +12,7 @@ For information on plugin hooks and objects, see :ref:`plugins`.
 
 For information on the ``pytest.mark`` mechanism, see :ref:`mark`.
 
-For information about fixtures, see :ref:`fixtures`. To see a complete list of available fixtures, type::
+For information about fixtures, see :ref:`fixtures`. To see a complete list of available fixtures (add ``-v`` to also see fixtures with leading ``_``), type ::
 
     $ pytest -q --fixtures
     cache
diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst
index 6f3debd8019..fbb922d796c 100644
--- a/doc/en/fixture.rst
+++ b/doc/en/fixture.rst
@@ -111,11 +111,11 @@ with a list of available function arguments.
 
 .. note::
 
-    You can always issue::
+    You can always issue ::
 
         pytest --fixtures test_simplefactory.py
 
-    to see available fixtures.
+    to see available fixtures (fixtures with leading ``_`` are only shown if you add the ``-v`` option).
 
 Fixtures: a prime example of dependency injection
 ---------------------------------------------------
@@ -141,7 +141,7 @@ automatically gets discovered by pytest. The discovery of
 fixture functions starts at test classes, then test modules, then
 ``conftest.py`` files and finally builtin and third party plugins.
 
-You can also use the ``conftest.py`` file to implement 
+You can also use the ``conftest.py`` file to implement
 :ref:`local per-directory plugins <conftest.py plugins>`.
 
 Sharing test data
diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst
index 0965c2a61fb..7b9bfba574f 100644
--- a/doc/en/getting-started.rst
+++ b/doc/en/getting-started.rst
@@ -166,6 +166,8 @@ Find out what kind of builtin :ref:`pytest fixtures <fixtures>` exist with the c
 
     pytest --fixtures   # shows builtin and custom fixtures
 
+Note that this command omits fixtures with leading ``_`` unless the ``-v`` option is added.
+
 Continue reading
 -------------------------------------
 
diff --git a/doc/en/test/plugin/terminal.rst b/doc/en/test/plugin/terminal.rst
index e07d4f72183..bcfe53f38b5 100644
--- a/doc/en/test/plugin/terminal.rst
+++ b/doc/en/test/plugin/terminal.rst
@@ -23,7 +23,7 @@ command line options
 ``--full-trace``
     don't cut any tracebacks (default is to cut).
 ``--fixtures``
-    show available function arguments, sorted by plugin
+    show available fixtures, sorted by plugin appearance (fixtures with leading ``_`` are only shown with '-v')
 
 Start improving this plugin in 30 seconds
 =========================================