From ac38d5b413528b24b9333a1020072674e563ee07 Mon Sep 17 00:00:00 2001
From: Alex Dusenbery <adusenbery@edx.org>
Date: Mon, 11 Mar 2019 14:02:20 -0400
Subject: [PATCH] Create a local .coveragerc file, update testing docs.

---
 .coveragerc-local | 51 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/testing.rst  | 34 ++++++++++++++++++++++++++++---
 2 files changed, 82 insertions(+), 3 deletions(-)
 create mode 100644 .coveragerc-local

diff --git a/.coveragerc-local b/.coveragerc-local
new file mode 100644
index 0000000000..fa3191ced9
--- /dev/null
+++ b/.coveragerc-local
@@ -0,0 +1,51 @@
+# .coveragerc for edx-platform
+[run]
+data_file = reports/.coverage
+source =
+    cms
+    common/djangoapps
+    common/lib/calc
+    common/lib/capa
+    common/lib/xmodule
+    lms
+    openedx
+    pavelib
+    scripts
+
+omit =
+    cms/envs/*
+    cms/manage.py
+    cms/djangoapps/contentstore/views/dev.py
+    cms/djangoapps/*/migrations/*
+    cms/djangoapps/*/features/*
+    cms/lib/*/migrations/*
+    lms/debug/*
+    lms/envs/*
+    lms/djangoapps/*/migrations/*
+    lms/djangoapps/*/features/*
+    common/djangoapps/terrain/*
+    common/djangoapps/*/migrations/*
+    openedx/core/djangoapps/*/migrations/*
+    openedx/core/djangoapps/debug/*
+    openedx/features/*/migrations/*
+
+concurrency=multiprocessing
+parallel = true
+
+[report]
+ignore_errors = True
+
+exclude_lines =
+   pragma: no cover
+   raise NotImplementedError
+
+[html]
+title = edx-platform Python Test Coverage Report
+directory = reports/cover
+
+[xml]
+output = reports/coverage.xml
+
+[paths]
+source =
+    /edx/app/edxapp/edx-platform
diff --git a/docs/testing.rst b/docs/testing.rst
index 78866c6c53..6942682513 100644
--- a/docs/testing.rst
+++ b/docs/testing.rst
@@ -208,6 +208,9 @@ To run a single django test class use this command::
 
     paver test_system -t lms/djangoapps/courseware/tests/tests.py::ActivateLoginTest
 
+Running a Single Test
+---------------------
+
 When developing tests, it is often helpful to be able to really just run
 one single test without the overhead of PIP installs, UX builds, etc. In
 this case, it is helpful to look at the output of paver, and run just
@@ -291,15 +294,40 @@ This is an example of how to run a single test and get stdout shown immediately,
 
     pytest cms/djangoapps/contentstore/tests/test_import.py -s
 
+How to output coverage locally
+------------------------------
+
 These are examples of how to run a single test and get coverage::
 
-    pytest cms/djangoapps/contentstore/tests/test_import.py --cov # cms example
-    pytest lms/djangoapps/courseware/tests/test_module_render.py --cov # lms example
+    pytest cms/djangoapps/contentstore/tests/test_import.py --cov --cov-conifg=.coveragerc-local # cms example
+    pytest lms/djangoapps/courseware/tests/test_module_render.py --cov --cov-conifg=.coveragerc-local # lms example
 
-Use this command to generate a coverage report::
+That ``--cov-conifg=.coveragerc-local`` option is important - without it, the coverage
+tool will look for paths that exist on our jenkins test servers, but not on your local devstack.
+
+How to spit out coverage for a single file with a list of each line that is missing coverage::
+
+   pytest lms/djangoapps/grades/tests/test_subsection_grade.py \
+       --cov=lms.djangoapps.grades.subsection_grade \
+       --cov-config=.coveragerc-local \
+       --cov-report=term-missing
+   ---------- coverage: platform linux2, python 2.7.12-final-0 ----------
+
+   Name                                        Stmts   Miss  Cover   Missing
+   -------------------------------------------------------------------------
+   lms/djangoapps/grades/subsection_grade.py     125     38    70%   47-51, 57, 80-81, 85, 89, 99, 109, 113, [...]
+
+Use this command to generate a coverage report (after previously running ``pytest``)::
 
     coverage report
 
+The above command looks for a test coverage data file in ``reports/.coverage`` - this file will
+contain coverage data from your last run of ``pytest``.  Coverage data is recorded for whichever
+paths you specified in your ``--cov`` option, e.g.::
+
+    --cov=.  # will track coverage for the entire project
+    --cov=path.to.your.module  # will track coverage only for "module"
+
 Use this command to generate an HTML report::
 
     coverage html