feat(watch mode): Add watch mode support with CLI options and enhanced documentation

readme.md

@@ -27,6 +27,12 @@
 - 🔁 **Retry Logic** - Automatically retry failing tests
 - 🛠️ **Test Fixtures** - Create reusable test data
 - 📦 **Browser-Compatible** - Full browser support with embedded tapbundle
+- 👀 **Watch Mode** - Automatically re-run tests on file changes
+- 📊 **Real-time Progress** - Live test execution progress updates
+- 🎨 **Visual Diffs** - Beautiful side-by-side diffs for failed assertions
+- 🔄 **Event-based Reporting** - Real-time test lifecycle events
+- ⚙️ **Test Configuration** - Flexible test settings with .tstest.json files
+- 🚀 **Protocol V2** - Enhanced TAP protocol with Unicode delimiters
 
 ## Installation
 
@@ -73,6 +79,9 @@ tstest "test/unit/*.ts"
 | `--timeout <seconds>` | Timeout test files after specified seconds |
 | `--startFrom <n>` | Start running from test file number n |
 | `--stopAt <n>` | Stop running at test file number n |
+| `--watch`, `-w` | Watch for file changes and re-run tests |
+| `--watch-ignore <patterns>` | Ignore patterns in watch mode (comma-separated) |
+| `--only` | Run only tests marked with .only |
 
 ### Example Outputs
 
@@ -203,9 +212,9 @@ tap.only.test('focus on this', async () => {
   // Only this test will run
 });
 
-// Todo test
-tap.todo('implement later', async () => {
-  // Marked as todo
+// Todo test - creates actual test object marked as todo
+tap.todo.test('implement later', async () => {
+  // This test will be counted but marked as todo
 });
 
 // Chaining modifiers
@@ -558,6 +567,115 @@ tapWrap.tap.test('wrapped test', async () => {
 
 ## Advanced Features
 
+### Watch Mode
+
+Automatically re-run tests when files change:
+
+```bash
+# Watch all files in the project
+tstest test/ --watch
+
+# Watch with custom ignore patterns
+tstest test/ --watch --watch-ignore "dist/**,coverage/**"
+
+# Short form
+tstest test/ -w
+```
+
+**Features:**
+- 👀 Shows which files triggered the re-run
+- ⏱️ 300ms debouncing to batch rapid changes
+- 🔄 Clears console between runs for clean output
+- 📁 Intelligently ignores common non-source files
+
+### Real-time Test Progress
+
+tstest provides real-time updates during test execution:
+
+```
+▶️  test/api.test.ts (1/4)
+   Runtime: node.js
+   ⏳ Running: api endpoint validation...
+   ✅ api endpoint validation (145ms)
+   ⏳ Running: error handling...
+   ✅ error handling (23ms)
+   Summary: 2/2 PASSED
+```
+
+### Visual Diffs for Failed Assertions
+
+When assertions fail, tstest shows beautiful side-by-side diffs:
+
+```
+❌ should return correct user data
+
+   String Diff:
+   - Expected
+   + Received
+   
+   - Hello World
+   + Hello Universe
+
+   Object Diff:
+   {
+     name: "John",
+   - age: 30,
+   + age: 31,
+     email: "john@example.com"
+   }
+```
+
+### Test Configuration (.tstest.json)
+
+Configure test behavior with `.tstest.json` files:
+
+```json
+{
+  "timeout": 30000,
+  "retries": 2,
+  "bail": false,
+  "parallel": true,
+  "tags": ["unit", "fast"],
+  "env": {
+    "NODE_ENV": "test"
+  }
+}
+```
+
+Configuration files are discovered in:
+1. Test file directory
+2. Parent directories (up to project root)
+3. Project root
+4. Home directory (`~/.tstest.json`)
+
+Settings cascade and merge, with closer files taking precedence.
+
+### Event-based Test Reporting
+
+tstest emits detailed events during test execution for integration with CI/CD tools:
+
+```json
+{"event":"suite:started","file":"test/api.test.ts","timestamp":"2025-05-26T10:30:00.000Z"}
+{"event":"test:started","name":"api endpoint validation","timestamp":"2025-05-26T10:30:00.100Z"}
+{"event":"test:progress","name":"api endpoint validation","message":"Validating response schema"}
+{"event":"test:completed","name":"api endpoint validation","passed":true,"duration":145}
+{"event":"suite:completed","file":"test/api.test.ts","passed":true,"total":2,"failed":0}
+```
+
+### Enhanced TAP Protocol (Protocol V2)
+
+tstest uses an enhanced TAP protocol with Unicode delimiters for better parsing:
+
+```
+⟦TSTEST:EVENT:test:started⟧{"name":"my test","timestamp":"2025-05-26T10:30:00.000Z"}
+ok 1 my test
+⟦TSTEST:EVENT:test:completed⟧{"name":"my test","passed":true,"duration":145}
+```
+
+This prevents conflicts with test output that might contain TAP-like formatting.
+
+## Advanced Features
+
 ### Glob Pattern Support
 
 Run specific test patterns:
@@ -731,6 +849,19 @@ tstest test/api/endpoints.test.ts --verbose --timeout 60
 
 ## Changelog
 
+### Version 1.11.0
+- 👀 Added Watch Mode with `--watch`/`-w` flag for automatic test re-runs
+- 📊 Implemented real-time test progress updates with event streaming
+- 🎨 Added visual diffs for failed assertions with side-by-side comparison
+- 🔄 Enhanced event-based test lifecycle reporting
+- ⚙️ Added test configuration system with `.tstest.json` files
+- 🚀 Implemented Protocol V2 with Unicode delimiters for better TAP parsing
+- 🐛 Fixed `tap.todo()` to create proper test objects
+- 🐛 Fixed `tap.skip.test()` to correctly create and count test objects
+- 🐛 Fixed `tap.only.test()` implementation with `--only` flag support
+- 📁 Added settings inheritance for cascading test configuration
+- ⏱️ Added debouncing for file change events in watch mode
+
 ### Version 1.10.0
 - ⏱️ Added `--timeout <seconds>` option for test file timeout protection
 - 🎯 Added `--startFrom <n>` and `--stopAt <n>` options for test file range control