commit-doc

Author: pfctdayelise

doc/en/new-docs/user.rst

@@ -11,7 +11,7 @@ Writing tests
 * :ref:`Test directory structure <testdirectory>`
 * :ref:`Asserting about exceptions with pytest.raises <pytestraises>`
 * :ref:`Using pytest.mark to group tests <pytestmarkbasic>`
-* :ref:`Skip and skipif marks <skipping>`
+* :ref:`Skip and skipif marks <skippingbasic>`
 * :ref:`xfail mark <xfail>`
 * :ref:`parametrize basics <parametrizebasic>`
 * :ref:`Fixture basics <fixturebasic>`

doc/en/new-docs/user/pytest_raises.rst

@@ -1,6 +1,35 @@
+.. _index: exceptions, pytest.raises
 .. _`pytestraises`:
 
 Asserting about exceptions with pytest.raises
 =============================================
 
-TODO
+An important aspect of unit testing is checking boundary/edge cases, and behaviour in the case of unexpected input. If you have a function that in some cases raises an exception, you can confirm this is working as expected using a context manager called ``pytest.raises``. Example::
+
+    import pytest
+
+    def test_zero_division():
+        with pytest.raises(ZeroDivisionError):
+            1 / 0
+
+
+If an exception is not raised in a ``pytest.raises`` block, the test will fail.  Example::
+
+    import pytest
+
+    def test_zero_division():
+        with pytest.raises(ZeroDivisionError):
+            2 / 1
+
+
+Running this will give the result::
+
+    _______________________ test_zero_division ____________________________
+
+        def test_zero_division():
+            with pytest.raises(ZeroDivisionError):
+    >           2 / 1
+    E           Failed: DID NOT RAISE
+
+
+A related concept is that of making a test as "expected to fail", or xfail (TODO-User-xfail).

doc/en/new-docs/user/pytestmark.rst

@@ -1,6 +1,93 @@
+.. _index: mark
 .. _`pytestmarkbasic`:
 
 Grouping tests with pytest.mark
 ===============================
 
-TODO
+The ``pytest.mark`` decorator can be used to add metadata to tests. This is useful to note related tests and to select groups of tests to be run. In the following example, only one test has the mark "webtest"::
+
+    # content of test_server.py
+
+    import pytest
+
+    @pytest.mark.webtest
+    def test_send_http():
+        pass # perform some webtest test for your app
+
+    def test_something_quick():
+        pass
+
+    def test_another():
+        pass
+
+
+    class TestClass:
+        def test_method(self):
+            pass
+
+
+You can then restrict a test run to only run tests marked with ``webtest`` by using the "-m" command line option::
+
+    $ py.test -v -m webtest
+    ======= test session starts ========
+    platform linux -- Python 3.5.1, pytest-2.9.2, py-1.4.31, pluggy-0.3.1 -- $PYTHON_PREFIX/bin/python3.5
+    cachedir: .cache
+    rootdir: $REGENDOC_TMPDIR, inifile: 
+    collecting ... collected 4 items
+    
+    test_server.py::test_send_http PASSED
+    
+    ======= 3 tests deselected by "-m 'webtest'" ========
+    ======= 1 passed, 3 deselected in 0.12 seconds ========
+
+Or the inverse, running all tests except the webtest ones::
+
+    $ py.test -v -m "not webtest"
+    ======= test session starts ========
+    platform linux -- Python 3.5.1, pytest-2.9.2, py-1.4.31, pluggy-0.3.1 -- $PYTHON_PREFIX/bin/python3.5
+    cachedir: .cache
+    rootdir: $REGENDOC_TMPDIR, inifile: 
+    collecting ... collected 4 items
+    
+    test_server.py::test_something_quick PASSED
+    test_server.py::test_another PASSED
+    test_server.py::TestClass::test_method PASSED
+    
+    ======= 1 tests deselected by "-m 'not webtest'" ========
+    ======= 3 passed, 1 deselected in 0.12 seconds ========
+
+
+You may use ``pytest.mark`` decorators with classes to apply markers to all of
+its test methods::
+
+    # content of test_mark_classlevel.py
+
+    import pytest
+
+    @pytest.mark.webtest
+    class TestClass:
+        def test_startup(self):
+            pass
+
+        def test_startup_and_more(self):
+            pass
+
+This is equivalent to directly applying the decorator to the
+two test functions.
+
+
+
+Some built-in markers offer extra functionality instead of grouping tests, for example:
+
+* :ref:`skipif <skipif??>` - skip a test function if a certain condition is met
+* :ref:`xfail <xfail??>` - produce an "expected failure" outcome if a certain
+  condition is met
+* :ref:`parametrize <parametrizemark??>` to perform multiple calls
+  to the same test function
+
+See also 
+
+* TODO (Basic - useful command line options)
+* TODO(Advanced - adding extra functionality to marks)
+* TODO (Advanced - ini - registering markers)
+* TODO (Plugin author - adding a custom marker from a plugin)

doc/en/new-docs/user/skip.rst

@@ -0,0 +1,90 @@
+.. _index: skip, skipif
+.. _`skippingbasic`:
+
+Skipping
+========
+
+If your software runs on multiple platforms, or supports multiple versions of
+different dependencies, it is likely that you will encounter bugs or strange
+edge cases that only occur in one particular environment. In this case, it can
+be useful to write a test for that should only be exercised on that
+environment, and in other cases it doesn't need to be run - it can be skipped.
+
+If you wish to skip something conditionally then you can use ``skipif`` instead.
+Here is an example of marking a test function to be skipped when run on a
+Python 2 interpreter::
+
+    import sys
+    @pytest.mark.skipif(sys.version_info < (3, 0),
+                        reason="requires Python3")
+    def test_function():
+        ...
+
+During test function setup the condition ("sys.version_info >= (3, 0)") is
+checked.  If it evaluates to True, the test function will be skipped with the
+specified reason.  Note that pytest enforces specifying a reason in order to
+report meaningful "skip reasons" (e.g. when using the command line options
+``-rs``).  If the condition is a string, it will be evaluated as python
+expression.
+
+Example output::
+
+    $ py.test -rs
+    ======= test session starts ========
+    platform linux -- Python 3.5.1, pytest-2.9.2, py-1.4.31, pluggy-0.3.1
+    rootdir: $REGENDOC_TMPDIR, inifile: 
+    collected 1 items
+    
+    test_function.py s
+    ======= short test summary info ========    
+    SKIP [1] test_function.py:4: requires Python3
+    ======= 1 skipped in 0.01 seconds ========    
+
+
+
+Re-using skipif decorators
+--------------------------
+
+You can also define the decorator once and re-use it::
+
+    import sys
+    python3_only = pytest.mark.skipif(sys.version_info < (3, 0),
+                                      reason="requires Python3")
+    @python3_only
+    def test_function1():
+        ...
+    
+    @python3_only
+    def test_function2():
+        ...
+    
+    @python3_only
+    def test_function3():
+        ...
+
+For larger test suites it's usually a good idea to have one file where you
+define the markers which you then consistently apply throughout your test
+suite.
+
+
+Unconditional skip
+------------------
+
+To skip a test without a condition use the ``pytest.mark.skip`` decorator which
+may be passed an optional ``reason``:
+
+.. code-block:: python
+
+    @pytest.mark.skip(reason="no way of currently testing this")
+    def test_the_unknown():
+        ...
+
+If you are skipping a test because it fails (e.g. a bug in your software that
+you want to track) the ``xfail`` marker is probably more appropiate.
+
+
+See also
+--------
+
+* Test results page
+* xfail