Document how to run tests 📝

1 files changed, 22 insertions, 1 deletions

diff --git a/tests/README.md b/tests/README.md
index efca6dd6..5334c271 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,5 +1,26 @@
 # Tests
 
+## Running the tests
+```bash
+# Run all tests
+cargo test
+
+# Run unit tests
+cargo test --lib
+
+# Run integration tests (the tests in this directory)
+cargo test --test typeset
+
+# Run all tests whose names contain a filter word
+cargo test --test typeset call
+```
+
+For experimenting it's often useful to have a test file you can quickly run. For that purpose you can have a file named `playground.typ` right in this directory (the file is ignored by git). The playground test will be executed whenever no other test matches the filter, so you can run it with (since no real test's name contains an underscore):
+```bash
+cargo test --test typeset _
+```
+
+## Directory structure
 Top level directory structure:
 - `full`: Tests of full documents.
 - `lang`: Tests for specific language features.
@@ -13,7 +34,7 @@ Directory structure for each category:
 - `png`: PNG files produced by tests.
 - `pdf`: PDF files produced by tests.
 
-To keep things small, please optimize the reference images:
+To keep things small, please optimize reference images before committing them:
 ```bash
 # One image
 oxipng -o max path/to/image.png