Adds Documentation For Running A Single Test (#1669)

Adds a portion to the testing README explaining how and when to run an
individual test file when working with tests. Additionally adds a table
of contents as the document has become quite long.

Signed-off-by: Hassan Abouelela <[email protected]>

1 files changed, 31 insertions, 0 deletions

diff --git a/tests/README.md b/tests/README.md
index 0192f916e..b7fddfaa2 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -4,6 +4,14 @@ Our bot is one of the most important tools we have for running our community. As
 
 _**Note:** This is a practical guide to getting started with writing tests for our bot, not a general introduction to writing unit tests in Python. If you're looking for a more general introduction, you can take a look at the [Additional resources](#additional-resources) section at the bottom of this page._
 
+### Table of contents:
+- [Tools](#tools)
+- [Running tests](#running-tests)  
+- [Writing tests](#writing-tests)
+- [Mocking](#mocking)
+- [Some considerations](#some-considerations)
+- [Additional resources](#additional-resources)
+
 ## Tools
 
 We are using the following modules and packages for our unit tests:
@@ -25,6 +33,29 @@ To ensure the results you obtain on your personal machine are comparable to thos
 
 If you want a coverage report, make sure to run the tests with `poetry run task test` *first*.
 
+## Running tests
+There are multiple ways to run the tests, which one you use will be determined by your goal, and stage in development.
+
+When actively developing, you'll most likely be working on one portion of the codebase, and as a result, won't need to run the entire test suite.
+To run just one file, and save time, you can use the following command:
+```shell
+poetry run task test-nocov <path/to/file.py>
+```
+
+For example:
+```shell
+poetry run task test-nocov tests/bot/exts/test_cogs.py
+```
+will run the test suite in the `test_cogs` file.
+
+If you'd like to collect coverage as well, you can append `--cov` to the command above.
+
+
+If you're done and are preparing to commit and push your code, it's a good idea to run the entire test suite as a sanity check:
+```shell
+poetry run task test
+```
+
 ## Writing tests
 
 Since consistency is an important consideration for collaborative projects, we have written some guidelines on writing tests for the bot. In addition to these guidelines, it's a good idea to look at the existing code base for examples (e.g., [`test_converters.py`](/tests/bot/test_converters.py)).