docs: improve tests documentation

core/docs/tests/index.md

@@ -1,85 +1,14 @@
 # Testing
 
-## Testing with python-trezor
+We have two types of tests in Core:
 
-Apart from the internal tests, Trezor Core has a suite of integration tests in the
-`python` monorepo's subdirectory. There are several ways to use that.
+1. Unit tests that are specific to Trezor Core.
+2. Common tests, which are common to both Trezor Core (Model T) and Legacy (Model one). Device tests belong to this category.
 
+## Core tests
 
-### 1. Running the full test suite
+See the `core/tests/` directory.
 
-_Note: You need Pipenv, as mentioned in the [build](../build/index.md) section._
+## Common tests
 
-In the `trezor-firmware` checkout, in the root of the monorepo, install the environment:
-```sh
-pipenv sync
-```
-And run the automated tests:
-```sh
-pipenv run make -C core test_emu
-```
-
-
-### 2. Running tests manually
-
-Install the pipenv environment as outlined above. Then switch to a shell inside the
-environment:
-
-```sh
-pipenv shell
-```
-
-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:
-```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 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 [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>`:
-
-```sh
-pytest -k nem      # only runs tests that have "nem" in the name
-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
+See the [README](../../../tests/README.md) file in `tests/`.

tests/README.md

@@ -0,0 +1,21 @@
+# Tests
+
+## Burn tests
+
+These tests are doing a simple read/write operations on the device to see if the hardware can endure high number of flash writes. Meant to be run on the device directly for a long period of time.
+
+## Device tests
+
+Device tests are integration tests that can be run against either emulator or on an actual device. The Debug mode is required. These tests can be run against both Model One and Model T.
+
+See the [README](device_tests/README.md) for instructions how to run it.
+
+## Fido tests
+
+Implement U2F/FIDO2 tests.
+
+## Upgrade tests
+
+These tests test upgrade from one firmware version to another. They initialize an emulator on some specific version and then pass its storage to another version to see if the firmware operates as expected. They use fixtures from https://firmware.corp.sldev.cz/upgrade_tests/ which can be downloaded using the `download_emulators.sh` script.
+
+See the [README](upgrade_tests/README.md) for instructions how to run it.

tests/device_tests/README.md

@@ -0,0 +1,75 @@
+# Running device tests
+
+## 1. Running the full test suite
+
+_Note: You need Pipenv, as mentioned in the core's [documentation](https://docs.trezor.io/trezor-firmware/core/) section._
+
+In the `trezor-firmware` checkout, in the root of the monorepo, install the environment:
+
+```sh
+pipenv sync
+```
+
+And run the automated tests:
+
+```sh
+pipenv run make -C core test_emu
+```
+
+## 2. Running tests manually
+
+Install the pipenv environment as outlined above. Then switch to a shell inside the
+environment:
+
+```sh
+pipenv shell
+```
+
+If you want to test against the emulator, run it in a separate terminal from the `core`
+subdirectory:
+```sh
+PYOPT=0 ./emu.sh
+```
+
+Now you can run the test suite with `pytest` from the root directory:
+```sh
+pytest tests/device_tests
+```
+
+### Useful Tips
+
+The tests are randomized using the [pytest-random-order] plugin. The random seed is printed in the header of the tests output, in case you need to run the tests in the same order.
+
+If you only want to run a particular test, pick it with `-k <keyword>` or `-m <marker>`:
+
+```sh
+pytest -k nem      # only runs tests that have "nem" in the name
+pytest -m stellar  # only runs tests marked with @pytest.mark.stellar
+```
+
+If you want to see debugging information and protocol dumps, run with `-v`.
+
+If you would like to interact with the device (i.e. press the buttons yourself), just prefix pytest with `INTERACT=1`:
+
+```sh
+INTERACT=1 pytest tests/device_tests
+```
+
+## 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.
+
+[pytest-random-order]: https://pypi.org/project/pytest-random-order/
+[REGISTERED_MARKERS]: ../REGISTERED_MARKERS

tests/download_emulators.sh

@@ -5,5 +5,4 @@ cd "$(dirname "$0")"
 # download all emulators without index files, without directories and only if not present
 wget --no-verbose --no-clobber --no-parent --cut-dirs=2 --no-host-directories --recursive --reject "index.html*" -P emulators/ $SITE
 
-# TODO: is this a good idea?
 chmod u+x emulators/trezor-emu-*

tests/upgrade_tests/README.md

@@ -0,0 +1,27 @@
+# Running Upgrade Tests
+
+1. As always, use pipenv environment:
+
+```sh
+pipenv shell
+```
+
+2. Download the emulators, if you have not already:
+
+```sh
+tests/download_emulators.sh
+```
+
+3. And run the tests using pytest:
+
+```sh
+pytest tests/upgrade_tests
+```
+
+----
+
+You can use `TREZOR_UPGRADE_TEST` environment variable if you would like to run core or legacy upgrade tests exclusively. This will run `core` only:
+
+```sh
+TREZOR_UPGRADE_TEST="core" pytest tests/upgrade_tests
+```