Merge pull request #3608 from avirlrma/features

add reamde for .pytest_cache

changelog/3519.trivial.rst

@@ -0,0 +1 @@
+Now a ``README.md`` file is created in ``.pytest_cache`` to make it clear why the directory exists.

src/_pytest/cacheprovider.py

@@ -15,6 +15,7 @@ import pytest
 import json
 import os
 from os.path import sep as _sep, altsep as _altsep
+from textwrap import dedent
 
 
 class Cache(object):
@@ -103,6 +104,26 @@ class Cache(object):
             with f:
                 self.trace("cache-write %s: %r" % (key, value))
                 json.dump(value, f, indent=2, sort_keys=True)
+                self._ensure_readme()
+
+    def _ensure_readme(self):
+
+        content_readme = dedent(
+            """\
+        # pytest cache directory #
+
+        This directory contains data from the pytest's cache plugin,
+        which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+        **Do not** commit this to version control.
+
+        See [the docs](https://docs.pytest.org/en/latest/cache.html) for more information.
+        """
+        )
+        if self._cachedir.check(dir=True):
+            readme_path = self._cachedir.join("README.md")
+            if not readme_path.check(file=True):
+                readme_path.write(content_readme)
 
 
 class LFPlugin(object):

testing/test_cacheprovider.py

@@ -6,7 +6,7 @@ import pytest
 import os
 import shutil
 
-pytest_plugins = "pytester",
+pytest_plugins = ("pytester",)
 
 
 class TestNewAPI(object):
@@ -818,3 +818,31 @@ class TestNewFirst(object):
                 "*test_1/test_1.py::test_1[2*",
             ]
         )
+
+
+class TestReadme(object):
+
+    def check_readme(self, testdir):
+        config = testdir.parseconfigure()
+        readme = config.cache._cachedir.join("README.md")
+        return readme.isfile()
+
+    def test_readme_passed(self, testdir):
+        testdir.makepyfile(
+            """
+            def test_always_passes():
+                assert 1
+        """
+        )
+        testdir.runpytest()
+        assert self.check_readme(testdir) is True
+
+    def test_readme_failed(self, testdir):
+        testdir.makepyfile(
+            """
+            def test_always_passes():
+                assert 0
+        """
+        )
+        testdir.runpytest()
+        assert self.check_readme(testdir) is True