[pypy-commit] pypy apptest-file: Update testing docs

[rlamy]

Author: Ronan Lamy <ronan.lamy at gmail.com>
Branch: apptest-file
Changeset: r97033:6662c6e06a92
Date: 2019-07-30 17:14 +0100
http://bitbucket.org/pypy/pypy/changeset/6662c6e06a92/

Log:	Update testing docs

diff --git a/pypy/doc/coding-guide.rst b/pypy/doc/coding-guide.rst
--- a/pypy/doc/coding-guide.rst
+++ b/pypy/doc/coding-guide.rst
@@ -456,13 +456,10 @@
 Testing modules in ``lib_pypy/``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can go to the :source:`pypy/module/test_lib_pypy/` directory and invoke the testing tool
-("py.test" or "python ../../pypy/test_all.py") to run tests against the
-lib_pypy hierarchy.  Note, that tests in :source:`pypy/module/test_lib_pypy/` are allowed
-and encouraged to let their tests run at interpreter level although
-:source:`lib_pypy/` modules eventually live at PyPy's application level.
-This allows us to quickly test our python-coded reimplementations
-against CPython.
+You can go to the :source:`pypy/module/test_lib_pypy/` directory and invoke the
+testing tool ("py.test" or "python ../../pypy/test_all.py") to run tests
+against the lib_pypy hierarchy.  This allows us to quickly test our
+python-coded reimplementations against CPython.
 
 
 Testing modules in ``pypy/module``
@@ -585,25 +582,42 @@
 module global level and use plain 'assert' statements thanks to the
 usage of the `py.test`_ tool.
 
-
-Application Level tests
+Application level tests
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 For testing the conformance and well-behavedness of PyPy it
 is often sufficient to write "normal" application-level
 Python code that doesn't need to be aware of any particular
-coding style or restrictions.  If we have a choice we often
-use application level tests which usually look like this::
+coding style or restrictions. If we have a choice we often
+use application level tests which are in files whose name starts with the
+`apptest_` prefix and look like this::
 
-    def app_test_something():
+    def test_this():
         # application level test code
 
+These application level test functions will run on top
+of PyPy, i.e. they have no access to interpreter details.
+
+By default, they run on top of an untranslated PyPy which runs on top of the
+host interpreter. When passing the `-D` option, they run directly on top of the
+host interpreter, which is usually a translated pypy executable in this case::
+
+    pypy3 -m pytest -D pypy/
+
+Note that in interpreted mode, only a small subset of pytest's functionality is
+available.
+
+Mixed-level tests (deprecated)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mixed-level tests are similar to application-level tests, the difference being
+that they're just snippets of app-level code embedded in an interp-level test
+file, like this::
+
     class AppTestSomething(object):
         def test_this(self):
             # application level test code
 
-These application level test functions will run on top
-of PyPy, i.e. they have no access to interpreter details.
 You cannot use imported modules from global level because
 they are imported at interpreter-level while you test code
 runs at application level. If you need to use modules
diff --git a/pypy/doc/contributing.rst b/pypy/doc/contributing.rst
--- a/pypy/doc/contributing.rst
+++ b/pypy/doc/contributing.rst
@@ -329,11 +329,18 @@
 Testing After Translation
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-While the usual invocation of `pytest` translates a piece of RPython code and
-runs it, we have a test extension to run tests without translation, directly
-on the host python. This is very convenient for modules such as `cpyext`, to
-compare and contrast test results between CPython and PyPy. Untranslated tests
-are invoked by using the `-A` or `--runappdirect` option to `pytest`::
+While the usual invocation of `pytest` runs app-level tests on an untranslated
+PyPy that runs on top of CPython, we have a test extension to run tests
+directly on the host python. This is very convenient for modules such as
+`cpyext`, to compare and contrast test results between CPython and PyPy.
+
+App-level tests run directly on the host interpreter when passing `-D` or
+`--apptest-direct` to `pytest`::
+
+    pypy3 -m pytest -D pypy/interpreter/test/apptest_pyframe.py
+
+Mixed-level tests are invoked by using the `-A` or `--runappdirect` option to
+`pytest`::
 
     python2 pytest.py -A pypy/module/cpyext/test