From 819d5cff24c7d5f71f6bb943cb703d68bc84c895 Mon Sep 17 00:00:00 2001
From: matejcik <ja@matejcik.cz>
Date: Thu, 9 Jul 2020 16:44:00 +0200
Subject: [PATCH] tests: add documentation for click-test recorder

---
 docs/SUMMARY.md                    |  1 +
 docs/tests/click-tests.md          | 67 ++++++++++++++++++++++++++++++
 tests/click_tests/record_layout.py |  8 ++++
 3 files changed, 76 insertions(+)
 create mode 100644 docs/tests/click-tests.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index ec5e3e1294..45f450ac2f 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -30,6 +30,7 @@
   - [Device Tests](tests/device-tests.md)
   - [Upgrade Tests](tests/upgrade-tests.md)
   - [UI Tests](tests/ui-tests.md)
+  - [Click Tests](tests/click-tests.md)
 - [CI](ci/index.md)
   - [GitLab CI Jobs](ci/jobs.md)
 - [Miscellaneous](misc/index.md)
diff --git a/docs/tests/click-tests.md b/docs/tests/click-tests.md
new file mode 100644
index 0000000000..525cff7d9f
--- /dev/null
+++ b/docs/tests/click-tests.md
@@ -0,0 +1,67 @@
+# Click Tests
+
+This set of tests is intended for cases where USB communication must be decoupled from
+the input stream. They are mainly based on sending simulated clicks and reading screen
+contents. Unlike device tests that use the `client` fixture, click tests generally
+use the `device_handler` fixture. TODO fixture documentation, the important point is
+that `device_handler` runs `trezorlib` calls in the background and leaves the main
+thread free to interact with the device from the user's perspective.
+
+## 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
+```
+
+Switch to a shell inside theenvironment:
+
+```sh
+pipenv shell
+```
+
+If you want to test against the emulator, run it in a separate terminal:
+```sh
+./core/emu.py
+```
+
+Now you can run the test suite with `pytest` from the root directory:
+```sh
+pytest tests/click_tests
+```
+
+## Click test recorder
+
+The repository now includes a tool for automatically generating testcases from user
+interaction. The resulting test cases must still be tweaked manually, but they can
+provide a solid starting point for a complex interaction pattern.
+
+**Caveat:** The testcase recorder is in alpha-stage, both in terms of functionality
+and code quality. Your mileage may vary.
+
+Run the tool with:
+
+```sh
+python tests/click_tests/record_layout.py
+```
+
+The tool accepts the same arguments as `trezorctl`. For example, to record yourself
+getting an address, use:
+
+```sh
+python tests/click_tests/record_layout.py btc get-address -n m/44h/0h/0h/0/0 -d
+```
+
+Instead of clicking buttons on the emulator, type commands in the terminal that ran
+the tool. A list of possible button clicks will be shown in your terminal. These will
+be sent to the emulator over debuglink.
+
+(Note that if a particular click does not react through the tool, there is a good chance
+that it won't work in the testcase either. Please file an issue.)
+
+After the session is over (when you type `stop`), the tool will collect all layout
+changes and output a testcase in pytest format. Copy-paste that into your test file
+and tweak as appropriate.
diff --git a/tests/click_tests/record_layout.py b/tests/click_tests/record_layout.py
index 9a81c6aa92..51e558db9a 100644
--- a/tests/click_tests/record_layout.py
+++ b/tests/click_tests/record_layout.py
@@ -1,3 +1,11 @@
+# click-test generator
+#
+# Beware: This tool is alpha-stage, both in terms of functionality and code quality.
+# It is published here because it can be useful as-is. But it's full of bugs in any
+# case.
+#
+# See docs/tests/click-tests.md for a brief instruction manual.
+
 import inspect
 import sys
 import threading