feat: implement comprehensive E2E test framework for proxy

.gitignore

@@ -205,6 +205,9 @@ credentials/*.credentials.json
 # Test samples directory
 test-samples/
 
+# E2E test credentials
+e2e/test-credentials/
+
 # Database backups
 *.sql
 claude_nexus_backup_*

bun.lock

@@ -11,7 +11,7 @@
         "@eslint/js": "^9.17.0",
         "@faker-js/faker": "^9.8.0",
         "@types/pg": "^8.11.10",
-        "bun-types": "latest",
+        "bun-types": "^1.2.17",
         "concurrently": "^8.2.2",
         "eslint": "^9.17.0",
         "husky": "^9.1.7",
@@ -180,7 +180,7 @@
 
     "braces": ["[email protected]", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
 
-    "bun-types": ["[email protected].15", "", { "dependencies": { "@types/node": "*" } }, "sha512-NarRIaS+iOaQU1JPfyKhZm4AsUOrwUOqRNHY0XxI8GI8jYxiLXLcdjYMG9UKS+fwWasc1uw1htV9AX24dD+p4w=="],
+    "bun-types": ["[email protected].17", "", { "dependencies": { "@types/node": "*" } }, "sha512-ElC7ItwT3SCQwYZDYoAH+q6KT4Fxjl8DtZ6qDulUFBmXA8YB4xo+l54J9ZJN+k2pphfn9vk7kfubeSd5QfTVJQ=="],
 
     "call-bind-apply-helpers": ["[email protected]", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
 
@@ -566,8 +566,6 @@
 
     "@humanfs/node/@humanwhocodes/retry": ["@humanwhocodes/[email protected]", "", {}, "sha512-JBxkERygn7Bv/GbN5Rv8Ul6LVknS+5Bp6RgDC/O8gEBU/yeH5Ui5C/OlWrTb6qct7LjjfT6Re2NxB0ln0yYybA=="],
 
-    "@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-ElC7ItwT3SCQwYZDYoAH+q6KT4Fxjl8DtZ6qDulUFBmXA8YB4xo+l54J9ZJN+k2pphfn9vk7kfubeSd5QfTVJQ=="],
-
     "@typescript-eslint/eslint-plugin/ignore": ["[email protected]", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
 
     "@typescript-eslint/typescript-estree/minimatch": ["[email protected]", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow=="],

e2e/.env.test

@@ -0,0 +1,23 @@
+# E2E Test Environment Configuration
+DATABASE_URL=postgresql://testuser:testpassword@localhost:5433/testdb
+PROXY_URL=http://localhost:3000
+DASHBOARD_API_KEY=test-dashboard-key
+STORAGE_ENABLED=true
+DEBUG=false
+DEBUG_SQL=false
+
+# Test credentials directory
+CREDENTIALS_DIR=./e2e/test-credentials
+
+# Test domain configuration
+TEST_DOMAIN=e2e-test.com
+TEST_CLIENT_API_KEY=cnp_test_1234567890
+TEST_CLAUDE_API_KEY=sk-ant-test-key
+
+# Proxy server configuration for tests
+PROXY_PORT=3000
+DASHBOARD_PORT=3001
+
+# Disable external services during tests
+SLACK_WEBHOOK_URL=
+SPARK_API_URL=

e2e/README.md

@@ -0,0 +1,163 @@
+# E2E Tests for Claude Nexus Proxy
+
+This directory contains end-to-end tests for the Claude Nexus Proxy service.
+
+## Overview
+
+The E2E test framework:
+
+- Executes real API requests through the proxy service
+- Validates conversation linking, branching, and persistence
+- Uses Docker PostgreSQL for authentic database testing
+- Supports both streaming and non-streaming responses
+- Uses JSON fixtures for test case definitions
+
+## Setup
+
+1. Install dependencies:
+
+```bash
+cd e2e
+bun install
+```
+
+2. Configure test environment:
+
+- Copy `.env.test.example` to `.env.test` if needed
+- Update `TEST_CLAUDE_API_KEY` with a valid test API key
+
+## Running Tests
+
+```bash
+# Run all E2E tests
+bun run test
+
+# Run tests in watch mode
+bun run test:watch
+
+# Run Docker services manually
+bun run docker:up
+bun run docker:logs
+bun run docker:down
+```
+
+## Test Fixtures
+
+Test cases are defined as JSON files in the `fixtures/` directory. Each fixture contains:
+
+- **authentication**: Domain and API keys for the test
+- **steps**: Sequential API requests to execute
+- **expected**: Validations for responses and database state
+
+### Fixture Format
+
+```json
+{
+  "name": "Test name",
+  "description": "Optional description",
+  "authentication": {
+    "domain": "e2e-test.com",
+    "clientApiKey": "cnp_test_xxx",
+    "claudeApiKey": "sk-ant-xxx"
+  },
+  "steps": [
+    {
+      "stepName": "unique_step_name",
+      "request": {
+        "body": {
+          /* Claude API request body */
+        }
+      },
+      "context": {
+        "save": {
+          "variableName": "path.to.value"
+        }
+      },
+      "expected": {
+        "response": {
+          "statusCode": 200,
+          "body": {
+            /* expected fields */
+          }
+        },
+        "dbState": {
+          "table": "api_requests",
+          "assert": {
+            /* expected DB fields */
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Special Keywords
+
+- `IS_UUID` - Validates UUID format
+- `!IS_NULL` - Ensures value is not null
+- `IS_NULL` - Ensures value is null
+- `NEW_CONVERSATION` - Generates new conversation ID
+- `REF_STEP:stepName.field` - References value from previous step
+- `${context.variable}` - Interpolates saved context variable
+
+### Operators
+
+For numeric comparisons:
+
+```json
+{
+  "stream_chunks_count": {
+    "operator": ">=",
+    "value": 5
+  }
+}
+```
+
+## Exporting Conversations
+
+Use the export script to copy conversations or requests from the database:
+
+```bash
+# Export full conversation
+bun run export -c <conversation-id>
+
+# Export specific requests
+bun run export -r request1,request2,request3
+
+# Export with streaming chunks
+bun run export -c <conversation-id> --include-chunks
+
+# Specify output file
+bun run export -c <conversation-id> -o my-conversation.json
+```
+
+## Architecture
+
+- **test-harness.ts** - Main test orchestrator
+- **runner.ts** - Test execution logic
+- **apiClient.ts** - Proxy API client
+- **dbClient.ts** - Database operations
+- **export-conversation.ts** - Data export utility
+
+The test framework:
+
+1. Starts Docker PostgreSQL
+2. Initializes database schema
+3. Creates test credentials
+4. Starts proxy server
+5. Executes test fixtures
+6. Validates responses and DB state
+7. Cleans up resources
+
+## Adding New Tests
+
+1. Create a new JSON file in `fixtures/`
+2. Define test steps with expected outcomes
+3. Run `bun run test` to execute
+
+## Debugging
+
+- Set `DEBUG=true` in `.env.test` for verbose logging
+- Check Docker logs: `bun run docker:logs`
+- Inspect database: Connect to `localhost:5433` with test credentials

e2e/bun.lock

@@ -0,0 +1,57 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@claude-nexus-proxy/e2e-tests",
+      "dependencies": {
+        "nanoid": "^5.0.4",
+        "pg": "^8.11.3",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "@types/pg": "^8.10.9",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.2.17" } }, "sha512-l/BYs/JYt+cXA/0+wUhulYJB6a6p//GTPiJ7nV+QHa8iiId4HZmnu/3J/SowP5g0rTiERY2kfGKXEK5Ehltx4Q=="],
+
+    "@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~7.8.0" } }, "sha512-ENHwaH+JIRTDIEEbDK6QSQntAYGtbvdDXnMXnZaZ6k13Du1dPMmprkEHIL7ok2Wl2aZevetwTAb5S+7yIF+enA=="],
+
+    "@types/pg": ["@types/[email protected]", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-I6UNVBAoYbvuWkkU3oosC8yxqH21f4/Jc4DK71JLG3dT2mdlGe1z+ep/LQGXaKaOgcvUrsQoPRqfgtMcvZiJhg=="],
+
+    "bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-ElC7ItwT3SCQwYZDYoAH+q6KT4Fxjl8DtZ6qDulUFBmXA8YB4xo+l54J9ZJN+k2pphfn9vk7kfubeSd5QfTVJQ=="],
+
+    "nanoid": ["[email protected]", "", { "bin": { "nanoid": "bin/nanoid.js" } }, "sha512-Ir/+ZpE9fDsNH0hQ3C68uyThDXzYcim2EqcZ8zn8Chtt1iylPT9xXJB0kPCnqzgcEGikO9RxSrh63MsmVCU7Fw=="],
+
+    "pg": ["[email protected]", "", { "dependencies": { "pg-connection-string": "^2.9.1", "pg-pool": "^3.10.1", "pg-protocol": "^1.10.3", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.2.7" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-enxc1h0jA/aq5oSDMvqyW3q89ra6XIIDZgCX9vkMrnz5DFTw/Ny3Li2lFQ+pt3L6MCgm/5o2o8HW9hiJji+xvw=="],
+
+    "pg-cloudflare": ["[email protected]", "", {}, "sha512-YgCtzMH0ptvZJslLM1ffsY4EuGaU0cx4XSdXLRFae8bPP4dS5xL1tNB3k2o/N64cHJpwU7dxKli/nZ2lUa5fLg=="],
+
+    "pg-connection-string": ["[email protected]", "", {}, "sha512-nkc6NpDcvPVpZXxrreI/FOtX3XemeLl8E0qFr6F2Lrm/I8WOnaWNhIPK2Z7OHpw7gh5XJThi6j6ppgNoaT1w4w=="],
+
+    "pg-int8": ["[email protected]", "", {}, "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw=="],
+
+    "pg-pool": ["[email protected]", "", { "peerDependencies": { "pg": ">=8.0" } }, "sha512-Tu8jMlcX+9d8+QVzKIvM/uJtp07PKr82IUOYEphaWcoBhIYkoHpLXN3qO59nAI11ripznDsEzEv8nUxBVWajGg=="],
+
+    "pg-protocol": ["[email protected]", "", {}, "sha512-6DIBgBQaTKDJyxnXaLiLR8wBpQQcGWuAESkRBX/t6OwA8YsqP+iVSiond2EDy6Y/dsGk8rh/jtax3js5NeV7JQ=="],
+
+    "pg-types": ["[email protected]", "", { "dependencies": { "pg-int8": "1.0.1", "postgres-array": "~2.0.0", "postgres-bytea": "~1.0.0", "postgres-date": "~1.0.4", "postgres-interval": "^1.1.0" } }, "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA=="],
+
+    "pgpass": ["[email protected]", "", { "dependencies": { "split2": "^4.1.0" } }, "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug=="],
+
+    "postgres-array": ["[email protected]", "", {}, "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA=="],
+
+    "postgres-bytea": ["[email protected]", "", {}, "sha512-xy3pmLuQqRBZBXDULy7KbaitYqLcmxigw14Q5sj8QBVLqEwXfeybIKVWiqAXTlcvdvb0+xkOtDbfQMOf4lST1w=="],
+
+    "postgres-date": ["[email protected]", "", {}, "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q=="],
+
+    "postgres-interval": ["[email protected]", "", { "dependencies": { "xtend": "^4.0.0" } }, "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ=="],
+
+    "split2": ["[email protected]", "", {}, "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg=="],
+
+    "undici-types": ["[email protected]", "", {}, "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw=="],
+
+    "xtend": ["[email protected]", "", {}, "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ=="],
+  }
+}