From 32fbdb2abdf615148ff4382e623f25fd9b5943df Mon Sep 17 00:00:00 2001
From: matejcik <ja@matejcik.cz>
Date: Mon, 27 May 2019 16:12:53 +0200
Subject: [PATCH] docs: update testing documentation

---
 core/docs/testing.md | 66 +++++++++++++++++++++++++-------------------
 1 file changed, 38 insertions(+), 28 deletions(-)

diff --git a/core/docs/testing.md b/core/docs/testing.md
index 3acbf4f89..22adbd019 100644
--- a/core/docs/testing.md
+++ b/core/docs/testing.md
@@ -2,70 +2,59 @@
 
 ## Testing with python-trezor
 
-Apart from the internal tests, Trezor core has a suite of integration tests in the `python` subdirectory. There are several ways to use that.
+Apart from the internal tests, Trezor core has a suite of integration tests in the
+`python` subdirectory. There are several ways to use that.
 
-### 1. Running the suite with pipenv
 
-[`pipenv`](https://docs.pipenv.org/) is a tool for making reproducible Python environments. Install it with:
+### 1. Running the full test suite
 
+[pipenv] is a tool for making reproducible Python environments. Install it with:
 ```sh
 sudo pip3 install pipenv
 ```
-
-Inside `trezor-core` checkout, install the environment:
-
+In the `frezor-firmware` checkout, install the environment:
 ```sh
-pipenv install
+pipenv sync
 ```
-
 And run the automated tests:
-
 ```sh
-pipenv run make test_emu
+pipenv run make -C core test_emu
 ```
 
-### 2. Developing new tests
 
-Prepare a virtual environment with all the requirements, and switch into it. Again, it's easiest to do this with `pipenv`:
+### 2. Running tests manually
+
+Install the pipenv environment as outlined above. Then switch to a shell inside the
+environment:
 
 ```sh
-pipenv install
 pipenv shell
 ```
 
-Alternately, if you have an existing virtualenv, you can install `python` in "develop" mode:
-
-```sh
-python setup.py develop
-```
-
-If you want to test against the emulator, run it in a separate terminal from the `core` subdirectory:
-
+If you want to test against the emulator, run it in a separate terminal from the `core`
+subdirectory:
 ```sh
 PYOPT=0 ./emu.sh
 ```
 
-Find the device address and export it as an environment variable. For the emulator, this is:
-
+Find the device address and export it as an environment variable. For the emulator, this
+is:
 ```sh
 export TREZOR_PATH="udp:127.0.0.1:21324"
 ```
-
 (You can find other devices with `trezorctl list`.)
 
-Now you can run the test suite, either from `python` or `core` root directory:
-
+Now you can run the test suite with `pytest`, either from `python` or `core` directory:
 ```sh
 pytest
 ```
 
 Or from anywhere else:
-
 ```sh
 pytest --pyargs trezorlib.tests.device_tests  # this works from other locations
 ```
 
-You can place your own tests in `trezorlib/tests/device_tests`. See test style guide (TODO).
+You can place your own tests in [device_tests] directory. See test style guide (TODO).
 
 If you only want to run a particular test, pick it with `-k <keyword>` or `-m <marker>`:
 
@@ -75,3 +64,24 @@ pytest -m stellar  # only runs tests marked with @pytest.mark.stellar
 ```
 
 If you want to see debugging information and protocol dumps, run with `-v`.
+
+
+### 3. Using markers
+
+When you're developing a new currency, you should mark all tests that belong to that
+currency. For example, if your currency is called NewCoin, your device tests should have
+the following marker:
+
+```python
+@pytest.mark.newcoin
+```
+
+This marker must be registered in [REGISTERED_MARKERS] file.
+
+If you wish to run a test only on TT, mark it with `@pytest.mark.skip_t1`.
+If the test should only run on T1, mark it with `@pytest.mark.skip_t2`.
+You must not use both on the same test.
+
+[pipenv]: https://docs.pipenv.org/
+[device_tests]: ../../python/trezorlib/tests/device_tests
+[REGISTERED_MARKERS]: ../../python/trezorlib/tests/device_tests/REGISTERED_MARKERS