From f42d7c67c935180908eb3507eb59a928c62e5afb Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Tue, 24 Feb 2026 08:03:34 -0600
Subject: docs: add Running Tests section to testing strategy, link from README

---
 README.org           |  4 +++-
 testing-strategy.org | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index f7950ef..1e67afb 100644
--- a/README.org
+++ b/README.org
@@ -353,7 +353,9 @@ operations only. Do not expose the live environment to untrusted networks.
 The test suite launches QEMU VMs to validate that the ISO boots correctly and
 that installations complete successfully across all supported configurations
 (ZFS/Btrfs, single/multi-disk, encrypted/unencrypted). Run these tests after
-modifying the installer or build scripts to catch regressions.
+modifying the installer or build scripts to catch regressions. See
+[[file:testing-strategy.org][testing-strategy.org]] for the full testing strategy, including how to add new
+tests and technical details on encryption testing.
 
 ** Basic VM Test
 
diff --git a/testing-strategy.org b/testing-strategy.org
index 3119917..6ae0e6f 100644
--- a/testing-strategy.org
+++ b/testing-strategy.org
@@ -7,6 +7,39 @@
 This document describes the testing strategy for the archzfs installer project,
 including automated VM testing and the rationale for key technical decisions.
 
+* Running Tests
+
+** Makefile Targets
+
+| Target | Description |
+|--------+-------------|
+| =make test-install= | Run all 12 automated install tests (builds ISO first) |
+| =make test-vm= | Boot ISO in a single-disk VM (interactive) |
+| =make test-multi= | Boot ISO in a 2-disk VM for mirror/RAID testing |
+| =make test-multi3= | Boot ISO in a 3-disk VM for raidz1 testing |
+| =make test-boot= | Boot from installed disk (after running install in VM) |
+| =make test-clean= | Remove VM disks and OVMF vars, start fresh |
+| =make lint= | Run shellcheck on all scripts |
+| =make test= | Run lint (alias) |
+
+** Running a Single Automated Test
+
+#+begin_src bash
+./scripts/test-install.sh zfs-encrypt
+#+end_src
+
+** Running Multiple Specific Tests
+
+#+begin_src bash
+./scripts/test-install.sh zfs-encrypt zfs-mirror-encrypt btrfs-luks
+#+end_src
+
+** Listing Available Test Configs
+
+#+begin_src bash
+./scripts/test-install.sh --list
+#+end_src
+
 * Test Infrastructure
 
 ** Test Scripts
-- 
cgit v1.2.3