From f807db5766b2e5d1c2218260ea195e02105258e9 Mon Sep 17 00:00:00 2001
From: Erwin <erwin@openclaw>
Date: Sat, 28 Mar 2026 03:32:19 +0000
Subject: [PATCH] docs: add TESTING.md with usage guide and test scenarios

---
 TESTING.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)
 create mode 100644 TESTING.md

diff --git a/TESTING.md b/TESTING.md
new file mode 100644
index 0000000..3671b1b
--- /dev/null
+++ b/TESTING.md
@@ -0,0 +1,180 @@
+# SimpleNote CLI - Testing Guide
+
+## Prerequisites
+
+The CLI requires a running SimpleNote Web server. See `simplenote-web/TESTING.md` for server setup.
+
+## Installation
+
+```bash
+cd simplenote-projects/simplenote-cli
+npm install
+npm link  # Makes 'simplenote' command available globally
+```
+
+## Configuration
+
+The CLI stores config in `~/.config/simplenote/config.json`:
+
+```json
+{
+  "apiUrl": "http://localhost:3000/api/v1",
+  "token": "your-token-here",
+  "activeLibrary": null
+}
+```
+
+## Setup Flow
+
+```bash
+# 1. Start the web server
+cd ../simplenote-web && npm start &
+
+# 2. Login with admin token
+simplenote auth login snk_initial_admin_token_change_me
+
+# 3. Create an API token (via curl since CLI doesn't have this)
+curl -X POST http://localhost:3000/api/v1/auth/token \
+  -H "Authorization: Bearer snk_initial_admin_token_change_me" \
+  -H "Content-Type: application/json" \
+  -d '{"label": "cli-token"}'
+
+# 4. Login with the new token
+simplenote auth login <new-token>
+
+# 5. Create a library
+simplenote lib create --name "Test Project"
+
+# 6. Set it as active (manual config edit)
+```
+
+## Commands
+
+### Auth
+
+```bash
+# Login with token
+simplenote auth login <token>
+
+# Check status
+simplenote auth status
+```
+
+### Libraries
+
+```bash
+# List root libraries
+simplenote lib list
+
+# List children of a library
+simplenote lib list --parent <library-id>
+
+# Get library details
+simplenote lib get <library-id>
+
+# Create library
+simplenote lib create --name "New Library"
+simplenote lib create --name "Child Library" --parent <parent-id>
+
+# Get full library tree
+simplenote lib tree
+simplenote lib tree <library-id>
+```
+
+### Documents
+
+```bash
+# List all documents
+simplenote doc list
+
+# List with filters
+simplenote doc list --tag backend
+simplenote doc list --library <library-id>
+simplenote doc list --type requirement
+simplenote doc list --status draft
+simplenote doc list --limit 10 --offset 0
+
+# Get document
+simplenote doc get <doc-id>
+
+# Create document
+simplenote doc create --title "My Document" --library <library-id>
+simplenote doc create --title "REQ-001" --tags "api,backend" --type requirement --priority high
+
+# Update document
+simplenote doc update <doc-id> --title "Updated Title"
+simplenote doc update <doc-id> --content "# New Content" --status approved
+
+# Delete document
+simplenote doc delete <doc-id>
+
+# Export document as markdown
+simplenote doc export <doc-id>
+
+# Add tags
+simplenote doc add-tags <doc-id> --tags "new-tag, another"
+```
+
+### Tags
+
+```bash
+# List all tags
+simplenote tag list
+
+# Get documents with tag
+simplenote tag docs backend
+```
+
+## Test Scenarios
+
+### End-to-End Flow
+
+```bash
+# Setup
+simplenote auth login <token>
+simplenote lib create --name "E2E Test"
+
+# Get the library ID from the output, then:
+LIB_ID=<library-id>
+
+# Create documents
+simplenote doc create --title "REQ-001: User Auth" --library $LIB_ID --type requirement --tags "auth,api"
+simplenote doc create --title "Note: API V2" --library $LIB_ID --tags "api,notes"
+
+# List and verify
+simplenote doc list --library $LIB_ID
+simplenote doc list --tag api
+
+# Update
+simplenote doc update <doc-id> --status approved
+
+# Export
+simplenote doc export <doc-id>
+
+# Cleanup
+simplenote doc delete <doc-id>
+simplenote lib delete $LIB_ID
+```
+
+### Edge Cases
+
+```bash
+# Missing library ID on create
+simplenote doc create --title "Orphan Doc"  # Should error
+
+# Non-existent document
+simplenote doc get fake-id-123  # Should error
+
+# Empty tag list
+simplenote tag list  # Should show 0 tags
+
+# Invalid filter
+simplenote doc list --type invalidtype  # Should return empty
+```
+
+### CLI-Specific Issues to Watch
+
+1. **Confirmation prompt for delete** - `simplenote doc delete <id>` has `inquirer` import but no actual confirmation prompt
+2. **Active library** - No command to set active library; requires manual config edit
+3. **Verbose output** - `--verbose` flag is defined but unused
+4. **Update with undefined content** - `if (options.content !== undefined)` works but `--content ""` would pass empty string (correct behavior)