1 files changed, 148 insertions, 0 deletions
diff --git a/secrets/test/README.md b/secrets/test/README.md
new file mode 100644
index 0000000..49d70b2
--- /dev/null
+++ b/secrets/test/README.md
@@ -0,0 +1,148 @@
+# szecret Test Suite
+
+Unit tests for the szecret secret management system.
+
+## Running Tests
+
+```bash
+# Run all tests
+./test/run.sh
+
+# Run specific test files
+./test/run.sh list get
+
+# Run a single test file directly
+./test/list.sh
+```
+
+## Test Structure
+
+```
+test/
+├── common.sh        # Shared utilities, setup/teardown, assertions
+├── run.sh           # Test runner entrypoint
+├── create-local.sh  # Tests for create-local command
+├── edge-cases.sh    # Edge case tests (special chars, unicode, etc.)
+├── ensure.sh        # Tests for ensure command
+├── get.sh           # Tests for get command
+├── list.sh          # Tests for list command
+├── local.sh         # Tests for put-local/get-local commands
+├── main.sh          # Tests for main entrypoint
+├── paths.sh         # Tests for where the store and public key are found
+├── put.sh           # Tests for put command
+└── ready.sh         # Tests for ready command
+```
+
+## Writing New Tests
+
+### Basic test file template
+
+```bash
+#!/bin/bash
+# Tests for <command> command
+
+this_dir="$(cd "$(dirname "$0")" && pwd)"
+source "${this_dir}/common.sh"
+
+test_something() {
+    # Test code here
+    pass "description of what passed"
+}
+
+test_something_else() {
+    # Test code here
+    pass "another test"
+}
+
+run_tests() {
+    test_something
+    test_something_else
+}
+
+[[ "${BASH_SOURCE[0]}" == "${0}" ]] && run_tests
+```
+
+### Available helpers
+
+From `common.sh`:
+
+| Function | Description |
+|----------|-------------|
+| `szecret <cmd> [args]` | Run a szecret command via main.sh |
+| `szecret_script <name> [args]` | Run a specific script directly (e.g., `szecret_script get secret-name`) |
+| `pass <msg>` | Print green PASS message |
+| `fail <msg>` | Print red FAIL message and exit |
+| `skip <msg>` | Print yellow SKIP message |
+| `assert_success <cmd>` | Assert command exits 0 |
+| `assert_failure <cmd>` | Assert command exits non-zero |
+| `assert_equals <expected> <actual> [msg]` | Assert string equality |
+| `assert_contains <haystack> <needle> [msg]` | Assert string contains substring |
+| `assert_file_exists <path> [msg]` | Assert file exists |
+
+### Environment variables
+
+Tests run in an isolated environment with these variables set:
+
+| Variable | Description |
+|----------|-------------|
+| `TEST_DIR` | Temporary directory for test artifacts |
+| `SZECRET_STORE` | Points to `$TEST_DIR/store` |
+| `SZECRET_PUBLIC_KEY` | Points to test public key |
+| `SZECRET_PRIVATE_KEY` | Points to test private key |
+
+The test environment is created automatically when `common.sh` is sourced and cleaned up on exit.
+
+## Design Notes
+
+### Isolation
+
+Each test file runs in its own subprocess with a fresh environment. This ensures tests don't interfere with each other. The `run.sh` runner executes each test file as a separate process.
+
+### Auto-setup
+
+The `common.sh` file automatically runs `setup` and registers the `teardown` trap when first sourced. A guard variable (`_SZECRET_TEST_INITIALIZED`) prevents duplicate initialization if common.sh is sourced multiple times.
+
+### Configurable paths
+
+The szecret scripts support these environment variables for testing:
+
+- `SZECRET_STORE` - Override the store directory
+- `SZECRET_PUBLIC_KEY` - Override the public key path
+- `SZECRET_PRIVATE_KEY` - Override the private key path
+
+This allows tests to use a temporary directory without affecting the real secret store.
+
+## Known Limitations
+
+### Trailing newlines
+
+Bash command substitution `$()` strips trailing newlines. This means:
+
+```bash
+# This will lose the trailing newline
+retrieved="$(szecret get my-secret)"
+```
+
+This is bash behavior, not a szecret bug. The encrypted data preserves trailing newlines correctly.
+
+### Interactive commands
+
+The `ensure` command prompts for private key input when run interactively. This flow isn't fully tested since it requires TTY input. The tests verify it fails gracefully in non-interactive mode.
+
+### Binary data
+
+The tests don't currently cover binary data. Secrets are expected to be text (the encryption handles binary, but shell pipelines may have issues with null bytes).
+
+## Adding Tests for New Commands
+
+1. Create `test/<command>.sh` following the template above
+2. Make it executable: `chmod +x test/<command>.sh`
+3. The runner will automatically discover and run it
+
+## CI Integration
+
+The test suite exits with code 0 on success, non-zero on failure. Example CI usage:
+
+```bash
+./secrets/test/run.sh || exit 1
+```