1 files changed, 84 insertions, 0 deletions
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..024a679
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,84 @@
+# HyperTerm Tests
+
+Test suite for HyperTerm prompt functionality and performance.
+
+## Test Files
+
+### test_prompt.sh
+Comprehensive test suite with full functionality testing.
+
+**Features:**
+- Individual function testing
+- Performance benchmarking
+- Git state testing
+- Interactive test mode (skipped in CI)
+- Non-interactive mode for CI/automation
+
+**Usage:**
+```bash
+cd tests
+bash test_prompt.sh                    # Interactive mode
+bash test_prompt.sh --non-interactive  # Non-interactive mode (for CI)
+```
+
+### quick_test.sh
+Fast validation test for immediate feedback.
+
+**Features:**
+- Quick function validation
+- Basic performance check
+- Works in current directory or creates temp repo
+
+**Usage:**
+```bash
+cd tests
+bash quick_test.sh
+```
+
+## Test Environment
+
+Tests create isolated environments to avoid affecting your working directory:
+- Temporary git repositories in `/tmp/`
+- Various git states (clean, dirty, staged, untracked)
+- Automatic cleanup on exit
+
+## Performance Testing
+
+Both test scripts include performance measurements:
+- Multiple iterations for accurate timing
+- Average execution time per prompt call
+- Performance classification (Excellent < 10ms, Good < 50ms)
+
+## Git States Tested
+
+- Clean repository
+- Modified files
+- Untracked files
+- Staged files
+- Mixed states
+- Ahead/behind tracking
+
+## Requirements
+
+- Git installed and available in PATH
+- Bash 4.0 or later
+- HyperTerm core files in `../hyperterm/core/`
+
+## Logging
+
+All tests use structured logging:
+- `[INFO]` - General information
+- `[SUCCESS]` - Successful operations
+- `[WARN]` - Warnings
+- `[ERROR]` - Errors
+
+## Interactive Mode
+
+The full test suite includes an interactive mode with commands:
+- `status` - Show git status
+- `prompt` - Show full prompt
+- `perf` - Run performance test
+- `states` - Test different git states
+- `modify` - Create test modifications
+- `clean` - Clean working directory
+- `exit` - Exit interactive mode