[TESTING.md] Enhance TESTING docs

docs/TESTS.md

@@ -1,115 +1,192 @@
 # Tests
 
-## Tools to install
+- [Tests](#tests)
+  - [Pytest](#pytest)
+    - [Installing Pytest](#installing-pytest)
+      - [Windows](#windows)
+      - [Linux / MacOS](#linux--macos)
+      - [Virtual environments](#virtual-environments)
+    - [Running the tests](#running-the-tests)
+      - [Failures](#failures)
+    - [Extra arguments](#extra-arguments)
+      - [Stop After First Failure [`-x`]](#stop-after-first-failure--x)
+      - [Failed Tests First [`--ff`]](#failed-tests-first---ff)
+      - [Recommended Workflow](#recommended-workflow)
+      - [Python Debugger](#python-debugger)
+  - [Extending your IDE](#extending-your-ide)
+  - [Additional information](#additional-information)
+    - [Adding to PATH](#adding-to-path)
+      - [Windows](#windows-1)
 
-We recommend you install [pytest](http://pytest.org/en/latest/) with the following plugins:
+---
 
--  [pytest-cache](http://pythonhosted.org/pytest-cache/)
--  [pytest-subtests](https://github.com/pytest-dev/pytest-subtests)
--  [pytest-pylint](https://github.com/carsongee/pytest-pylint)
+## Pytest
 
-The PyTest [Getting Started Guide](https://docs.pytest.org/en/latest/getting-started.html) has quick general instructions, although they do not cover installing the plugins.
-Continue reading below for plugin installation.
+_Official Pytest documentation can be found on the [Pytest Wiki](https://pytest.org/en/latest/) page._
 
-We also recommend [pylint](https://pylint.pycqa.org/en/latest/user_guide/), as it is part of our automated feedback on the website, and can be a very useful (if noisy!) code analysis tool.
+Pytest lets you test your solutions using our provided tests, and is what we use to validate your solutions on the website.
 
-Pylint can be a bit much, so this [tutorial](https://pylint.pycqa.org/en/latest/tutorial.html) can be helpful for getting started, as can this overview of [Code Quality: Tools and Best Practices](https://realpython.com/python-code-quality/) from Real Python.
+### Installing Pytest
 
-Finally, [this site](https://pycodequ.al/docs/pylint-messages.html) is a great place to look up more human-readable descriptions of Pylint linting messages.
+Pytest can be installed and updated using the built-in Python utility `pip`.
 
+#### Windows
 
-### Installing `pytest`
+```powershell
+PS C:\Users\foobar> python3 -m pip install pytest pytest-cache pytest-subtests pytest-pylint
+Successfully installed pytest-6.2.5 ...
+```
 
-To install `pytest`, run the following command in the environment (_active `venv`, `conda env`, `docker container`, `vm` or other project space with Python 3.8 installed_):
+#### Linux / MacOS
 
 ```bash
-pip3 install pytest pytest-cache pytest-subtests pytest-pylint
-```
+$ sudo python3 -m pip install pytest pytest-cache pytest-subtests pytest-pylint
+Successfully installed pytest-6.2.5 ...
 
-If you get a `command not found` response from your system, you can find a
-tutorial on how to install `pip`
-[here](https://pip.pypa.io/en/stable/installing/).
+```
 
-Once the installation has completed, you can check what the default version of `pytest` is by running the following:
+To check if the installation was succesful:
 
 ```bash
-pytest --version
+$ python3 -m pytest --version
+pytest 6.2.5
 ```
 
-## Testing
+If you do not want to precede every command with `python3 -m` please refer to [adding to PATH](#adding-to-path) at the end of this document.
+
+#### Virtual environments
 
-### Run All Tests for an Exercise
+*For more information about virtual environments please refer to the [TOOLS](.\TOOLS.md) file.*
 
-To run all tests for a specific exercise (_we will take the `bob.py` exercise as
-an example here_), navigate to the directory where that exercise has been
-downloaded and run the following in the terminal:
+When installing Pytest or any other module(s), make sure that you have [activated your environment](.\TOOLS.md#activating-your-environment). After which you can run:
 
 ```bash
-pytest bob_test.py
+$ pip install pytest pytest-cache pytest-subtests pytest-pylint
+Successfully installed pytest-6.2.5 ...
 ```
 
-**Note:** To run the tests you need to pass the name of the testsuite file to
-`pytest` (_generally, this will be the file ending with `_test.py`_), **NOT** the file that was
-created to solve the exercsim problem (which is the _solution implementation_).
-`PyTest` needs the test definitions in the `_test.py` file in order to know how to call, run, and exercise the _solution implementation_ code.
-Since there are no test cases defined in the _solution implementation_, `pytest` will just return a positive result, specifying that it found and ran zero tests. Like this:
+### Running the tests
 
+To run the tests, go to the folder where the exercise is stored using `cd` in your terminal (_replace `{exercise-folder-location}` below with the path_).
 
+```bash
+$ cd {exercise-folder-location}
 ```
-=============================  bob.py  ==============================
 
----------------------------------------------------------------------
+The file you'll want always ends with `_test.py`.
+This file contains the tests for your solution, and are the same tests which run on the website.
+Now run the following command in your terminal, replacing `{exercise_test.py}` with the location/name of the test file:
+
+```bash
+$ python3 -m pytest {exercise_test.py}
+==================== 7 passed in 0.08s ====================
+```
 
-Ran 0 tests in 0.000s
+#### Failures
 
-OK
+When your code returns an incorrect or unexpected value, pytest returns all the failed tests and the returned and expected values of each. Look at the following failed test file:
+
+```bash
+$ python3 -m pytest {exercise_test.py}
+=================== FAILURES ====================
+______________ name_of_failed_test ______________
+# Test code inside of {exercise_test.py} that failed.
+...
+E   TypeOfError: ReturnedValue != ExpectedValue
+
+exercise_test.py:{line_of_failed_test}: TypeOfError
+============ short test summary info ============
+FAILED exercise_test.py::ExerciseTest::name_of_failed_test
+========== 1 failed, 2 passed in 0.13s ==========
 ```
 
+### Extra arguments
 
-### More `pytest` Examples
+If you really want to be specific about what Pytest returns on your screen, here are some handy arguments that allows you to configure its behavior.
 
-Below are some additional examples and details for getting up and running quickly with Pytest.
-[How to invoke pytest](https://docs.pytest.org/en/latest/how-to/usage.html#usage) and [pytest command-line flags](https://docs.pytest.org/en/latest/reference/reference.html#command-line-flags) offer full details on all of pytests run options.
+#### Stop After First Failure [`-x`]
 
+Running the `pytest -x {exercise_test.py}` command, will run the tests like normal, but will stop the tests when it encounters a failed test. This will help when you want to debug a single failure at a time.
 
-#### Stop After First Failure
-The above will run all the tests, whether they fail or not. If you'd rather stop
-the process and exit on the first failure, run:
+```bash
+$ python -m pytest -x example_test.py
+=================== FAILURES ====================
+_______________ example_test_foo ________________
+...
+...
+============ short test summary info ============
+FAILED example_test.py::ExampleTest::example_test_foo
+!!!!!!!!!!! stopping after 1 failures !!!!!!!!!!!
+========== 1 failed, 5 passed in 0.28s ==========
+```
+
+#### Failed Tests First [`--ff`]
+
+`pytest-cache` remembers which tests failed last time you ran `pytest`, running `pytest --ff {exercise_test.py}` will run those previously failed tests first, then it will continue with the rest of the tests. This might speed up your testing if you are making a lot of smaller fixes.
 
 ```bash
-pytest -x bob_test.py
+$ python -m pytest --ff bob_test.py
+==================== 7 passed in 503s ====================
 ```
 
-#### Failed Tests First
+#### Recommended Workflow
+
+We recommend using the following commands to make your debugging easier and (possibly) faster:
 
-`pytest-cache` remembers which tests failed, and can run those tests first.
+First change your working directory to the directory of the exercise you want to test:
 
 ```bash
-pytest --ff bob_test.py
+cd path/to/exercise
 ```
 
-#### Running All Tests for All Exercises
+Then, run the tests together with the previously explained arguments `-x` and`--ff`:
 
 ```bash
-cd exercism/python/
-pytest
+pytest -x -ff bob_test.py
 ```
 
-## Recommended Workflow
+This will test your solution. When `pytest` encounters a failed test, the program will stop and tell you which test failed. When you run the test again, `pytest` will first test that failed test, then continue with the rest.
 
-Try this command while working on exercises:
+#### Python Debugger
+
+If you want to truly debug like a pro, use the `--pdb` argument after the `pytest` command. 
 
 ```bash
-cd exercism/python/bob
-pytest -x --ff bob_test.py
+$ python3 -m pytest --pdb bob_test.py
+=============== 4 passed in 0.15s ===============
 ```
 
-## PDB
+When a test fails, `PDB` allows you to look at variables and how your code responds. If you want to learn how to use the `PDB` module, have a look at the [Python Docs](https://docs.python.org/3/library/pdb.html#module-pdb) or [this](https://realpython.com/python-debugging-pdb/) Real Python article.
+
+## Extending your IDE
+
+If you'd like to extend your IDE with some tools that will help you with testing and improving your code, check [this](./TOOLS.md) page. We go into multiple IDEs, editors and some useful extensions.
+
+## Additional information
 
-Typing pdb on the command line will drop you into the python debugger when a test fails.
-To learn how to usepdb, check out the
-[documentation](https://docs.python.org/3/library/pdb.html#debugger-commands).
+### Adding to PATH
+
+**Note:** If you are running a [virtual environment](.\TOOLS.md) you do not need to *add to path* as it should work fine.
+
+Preceding every module you want to run with `python3 -m` might get a little annoying. You can add the `Scripts` folder of your Python installation to your path. If you do not know where you have installed Python, run the following command in your terminal:
 
 ```bash
-pytest --pdb bob_test.py
+$ python3 -c "import os, sys; print(os.path.dirname(sys.executable))"
+{python_directory}
 ```
+
+The *returned* directory is where your Python version is installed, in this tutorial it is referred to as `{python_directory}`.
+
+#### Windows
+
+Click the `Windows Start` button and lookup *Edit the system environment variables* and press enter. Next press, `Environment Variables...`:
+
+![Press the blue button, lol](https://raw.githubusercontent.com/exercism/python/main/docs/img/Windows-SystemProperties.png)
+
+Then find the `Path` variable in your *User variables*, select it, and click `Edit...`:
+
+![Selecting the path variable](https://raw.githubusercontent.com/exercism/python/main/docs/img/Windows-EnvironmentVariables.png)
+
+Then add a new line, as shown in the picture, replacing `{python_directory}` with your Python installation's directory:
+
+![Add python to path](https://raw.githubusercontent.com/exercism/python/main/docs/img/Windows-AddPythonPath.png)