From 28d05aeacb0aa0f228179058e9def29f2eae6186 Mon Sep 17 00:00:00 2001 From: "M. Eric Irrgang" Date: Sun, 29 Nov 2020 19:54:39 +0000 Subject: [PATCH] Improve accessibility of pytest documentation. * Update gmxapi install.rst. * Consolidate (and prune) some README.md content in python_packaging subdirectory. Also ref #3706 Fixes #3702 --- docs/gmxapi/userguide/install.rst | 27 ++++++++++++++++--- python_packaging/README.md | 39 +++++++++++++++++++++++++++ python_packaging/test/README.md | 45 ------------------------------- 3 files changed, 62 insertions(+), 49 deletions(-) delete mode 100644 python_packaging/test/README.md diff --git a/docs/gmxapi/userguide/install.rst b/docs/gmxapi/userguide/install.rst index 65d80d8818..7e96486f7f 100644 --- a/docs/gmxapi/userguide/install.rst +++ b/docs/gmxapi/userguide/install.rst @@ -196,16 +196,21 @@ Documentation build requirements See :ref:`gmxapi_package_documentation` -.. _testing_requirements: +.. _testing requirements: Testing requirements -------------------- +Note that the test suite is only available in the GROMACS source tree. +(It is not part of the installed package.) +Acquire the GROMACS sources with :command:`git` or by downloading an archive, as documented elsewhere. + Testing is performed with `pytest `_. -Tests also require numpy_. -You can probably install both with pip_:: - pip install pytest numpy +:file:`python_packaging/requirements-test.txt` lists additional requirements for testing. +With pip_:: + + pip install -r python_packaging/requirements-test.txt To test the full functionality also requires an MPI parallel environment. You will need the mpi4py_ Python package and an MPI launcher @@ -514,6 +519,20 @@ https://hub.docker.com/r/gmxapi/docs for more information. Document sample_restraint package. Reference issue `3027 `_ +Testing +======= + +Note `testing requirements`_ above. + +After installing the :py:mod:`gmxapi` Python package, +you can run the Python test suite from the GROMACS source tree. +Example:: + + # Assuming you are in the root directory of the repository: + pytest python_packaging/src/test/ + +Refer to :file:`python_packaging/README.md` for more detailed information. + .. _gmxapi install troubleshooting: Troubleshooting diff --git a/python_packaging/README.md b/python_packaging/README.md index faa48c6a16..e6824acb44 100644 --- a/python_packaging/README.md +++ b/python_packaging/README.md @@ -155,3 +155,42 @@ satisfying dependencies for a new virtualenv does not require network access or Some dependencies (notably, a Python installation itself) may require some fiddling with the XCode SDK. https://developer.apple.com/documentation/xcode_release_notes/xcode_10_release_notes#3035624 + +# Tests for gmxapi Python packages distributed with GROMACS + +## Requirements + +Python tests use the `unittest` standard library module and the `unittest.mock` +submodule, included in Python 3.3+. + +The additional `pytest` package allows tests to be written more easily and +concisely, with easier test fixtures (through decorators), log handling, and +other output handling. + +## Files + +Python files beginning with `test_` are collected by the Python testing +framework during automatic test discovery. + +`conftest.py` and `pytest.ini` provide configuration for `pytest`. + +## Usage + +For basic tests, install the Python package(s) (presumably into a virtualenv), +then use the `pytest` executable to run these tests against the installed +package(s). + +`pytest $LOCAL_REPO_DIR/python_packaging/src/test` + +where `$LOCAL_REPO_DIR` is the path to the local copy of the GROMACS source repository. + +For multi-process tests, run with an MPI execution wrapper and the `mpi4py` module. + +`mpiexec -n 2 python -m mpi4py -m pytest $LOCAL_REPO_DIR/python_packaging/test` + +## Controlling output + +Refer to pytest documentation for command line options to control the type and detail of output. +Some high level overview and basic tasks are online at https://docs.pytest.org/en/3.9.3/usage.html +but you should run `pytest -h` in a terminal to get the complete set of available options +(in particular, note *log_cli* and *log_level*). diff --git a/python_packaging/test/README.md b/python_packaging/test/README.md deleted file mode 100644 index 413faf8b3b..0000000000 --- a/python_packaging/test/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Tests for gmxapi Python packages distributed with GROMACS - -Potentially longer-running than the unit tests in the Python package directory -and broader in scope. Intended to include more thorough and complete integration -testing than in the `acceptance` subdirectory. - -## Requirements - -Python tests use the `unittest` standard library module and the `unittest.mock` -submodule, included in Python 3.3+. - -The additional `pytest` package allows tests to be written more easily and -concisely, with easier test fixtures (through decorators), log handling, and -other output handling. - -## Files - -Python files beginning with `test_` are collected by the Python testing -framework during automatic test discovery. - -`conftest.py` and `pytest.ini` provide configuration for `pytest`. - -Tests are organized according to the functional requirements -documented in `roadmap.rst` in the `python_packaging` directory. - -## Usage - -For basic tests, install the Python package(s) (presumably into a virtualenv), -then use the `pytest` executable to run these tests against the installed -package(s). - -`pytest $LOCAL_REPO_DIR/python_packaging/test` - -where `$LOCAL_REPO_DIR` is the path to the local copy of the GROMACS source repository. - -For multi-process tests, run with an MPI execution wrapper and the `mpi4py` module. - -`mpiexec -n 2 python -m mpi4py -m pytest $LOCAL_REPO_DIR/python_packaging/test` - -## Controlling output - -Refer to pytest documentation for command line options to control the type and detail of output. -Some high level overview and basic tasks are online at https://docs.pytest.org/en/3.9.3/usage.html -but you should run `pytest -h` in a terminal to get the complete set of available options -(in particular, note *log_cli* and *log_level*). -- 2.22.0