From 661013c3e922c17f2dcf90a96bcc74b95a681475 Mon Sep 17 00:00:00 2001
From: Tomer Keren <tomer.keren.dev@gmail.com>
Date: Mon, 15 Oct 2018 11:13:24 +0300
Subject: [PATCH 1/4] Add testdir examples to CONTRIBUTING guide

Hopefully Closes: #4151
---
 CONTRIBUTING.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index c005c2fb2..eb36122b5 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -280,6 +280,37 @@ Here is a simple overview, with pytest-specific bits:
     base: features        # if it's a feature
 
 
+Writing Tests
+----------------------------
+
+Writing tests for plugins or for pytest itself is done using the `testdir fixture <https://docs.pytest.org/en/latest/reference.html#testdir>`_,
+
+For example:
+
+.. code-block:: python
+
+    def test_true_assertion(testdir):
+        testdir.makepyfile(
+            """
+            def test_foo():
+                assert True
+        """
+        )
+        result = testdir.runpytest()
+        result.assert_outcomes(failed=0, passed=1)
+
+
+    def test_true_assertion(testdir):
+        testdir.makepyfile(
+            """
+            def test_foo():
+                assert False
+        """
+        )
+        result = testdir.runpytest()
+        result.assert_outcomes(failed=1, passed=0)
+
+
 Joining the Development Team
 ----------------------------
 

From 99d957bd3df2bd4fcb4a4603a2073d6fc448b1e6 Mon Sep 17 00:00:00 2001
From: Tomer Keren <tomer.keren.dev@gmail.com>
Date: Mon, 15 Oct 2018 11:36:31 +0300
Subject: [PATCH 2/4] Check off PR requirements

---
 AUTHORS                | 1 +
 changelog/4151.doc.rst | 1 +
 2 files changed, 2 insertions(+)
 create mode 100644 changelog/4151.doc.rst

diff --git a/AUTHORS b/AUTHORS
index 2be74441a..463810bd9 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -209,6 +209,7 @@ Thomas Hisch
 Tim Strazny
 Tom Dalton
 Tom Viner
+Tomer Keren
 Trevor Bekolay
 Tyler Goodlet
 Tzu-ping Chung
diff --git a/changelog/4151.doc.rst b/changelog/4151.doc.rst
new file mode 100644
index 000000000..da561002a
--- /dev/null
+++ b/changelog/4151.doc.rst
@@ -0,0 +1 @@
+Add tempir testing example to CONTRIBUTING.rst guide

From f129ba617f8d481ba8469f2e039a574c8717b312 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 15 Oct 2018 08:00:16 -0300
Subject: [PATCH 3/4] Improve docs a bit

---
 CONTRIBUTING.rst | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index eb36122b5..c8ef03209 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -283,9 +283,9 @@ Here is a simple overview, with pytest-specific bits:
 Writing Tests
 ----------------------------
 
-Writing tests for plugins or for pytest itself is done using the `testdir fixture <https://docs.pytest.org/en/latest/reference.html#testdir>`_,
+Writing tests for plugins or for pytest itself is often done using the `testdir fixture <https://docs.pytest.org/en/latest/reference.html#testdir>`_, as a "black-box" test.
 
-For example:
+For example, to ensure a simple test passes you can write:
 
 .. code-block:: python
 
@@ -300,6 +300,11 @@ For example:
         result.assert_outcomes(failed=0, passed=1)
 
 
+Alternatively, it is possible to make checks based on the actual output of the termal using
+*glob-like* expressions:
+
+.. code-block:: python
+
     def test_true_assertion(testdir):
         testdir.makepyfile(
             """
@@ -308,7 +313,12 @@ For example:
         """
         )
         result = testdir.runpytest()
-        result.assert_outcomes(failed=1, passed=0)
+        result.stdout.fnmatch_lines(["*assert False*, "*1 failed*"])
+        
+When choosing a file where to write a new test, take a look at the existing files and see if there's
+one file which looks like a good fit. For example, a regression test about a bug in the ``--lf`` option
+should go into ``test_cacheprovider.py``, given that this option is implemented in ``cacheprovider.py``.
+If in doubt, go ahead and open a PR with your best guess and we can discuss this over the code.
 
 
 Joining the Development Team

From ea25eb1ecc679cb1ef3a88aefe7d6bc30fa978c2 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 15 Oct 2018 08:15:40 -0300
Subject: [PATCH 4/4] Fix linting

---
 CONTRIBUTING.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index c8ef03209..d3202f7c8 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -313,8 +313,8 @@ Alternatively, it is possible to make checks based on the actual output of the t
         """
         )
         result = testdir.runpytest()
-        result.stdout.fnmatch_lines(["*assert False*, "*1 failed*"])
-        
+        result.stdout.fnmatch_lines(["*assert False*", "*1 failed*"])
+
 When choosing a file where to write a new test, take a look at the existing files and see if there's
 one file which looks like a good fit. For example, a regression test about a bug in the ``--lf`` option
 should go into ``test_cacheprovider.py``, given that this option is implemented in ``cacheprovider.py``.