feat: add --test filter flag for targeted test runs

README.md

@@ -24,6 +24,31 @@ Run tests with default configuration:
 npx twd-cli run
 ```
 
+### Filtering tests
+
+Run only a subset of tests with the repeatable `--test` flag. Matching is
+**case-insensitive** and matches a **substring** of each test's full
+`"Suite > test name"` path:
+
+```bash
+# Run every test whose name contains "shows error"
+npx twd-cli run --test "shows error"
+
+# Because matching uses the full "suite > test" path, passing a describe
+# name runs every test inside that describe block:
+npx twd-cli run --test "Login"
+
+# Multiple --test flags are combined with OR (a test runs if it matches any):
+npx twd-cli run --test "Login" --test "Signup"
+```
+
+Notes:
+
+- If no test matches any filter, the run exits with code `1` and prints
+  `No tests matched filter(s): …` — so a typo won't silently look like a pass.
+- Code coverage collection is skipped while a `--test` filter is active, since a
+  filtered run is a partial (debug) run.
+
 ### Configuration
 
 Create a `twd.config.json` file in your project root:

bin/twd-cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
 import { runTests } from '../src/index.js';
+import { parseRunArgs } from '../src/parseArgs.js';
 
 const command = process.argv[2];
 
 if (command === 'run') {
   try {
-    const hasFailures = await runTests();
+    const { testFilters } = parseRunArgs(process.argv.slice(3));
+    const hasFailures = await runTests({ testFilters });
     process.exit(hasFailures ? 1 : 0);
   } catch (error) {
     process.exit(1);
@@ -16,7 +18,14 @@ if (command === 'run') {
 twd-cli - Test runner for TWD tests
 
 Usage:
-  npx twd-cli run    Run all tests
+  npx twd-cli run                  Run all tests
+  npx twd-cli run --test "<name>"  Run only tests whose "suite > test" path
+                                   contains <name> (case-insensitive).
+                                   Repeatable; multiple --test values are OR'd.
+
+Examples:
+  npx twd-cli run --test "shows error"
+  npx twd-cli run --test "Login" --test "Signup"
 
 Options:
   Create a twd.config.json file in your project root to customize settings.