Skip to content

Commit 37010be

Browse files
noelsaw1noelsaw1
committed
feat: wp-ajax-test tool specification
- Add tools/wp-ajax-test/SPEC.md (complete tool specification) - Add tools/wp-ajax-test/AI-INSTRUCTIONS.md (AI agent guidance) - Design principle: Centralized by default, local copy when needed - AI agents call ~/bin/ai-ddtk/bin/wp-ajax-test directly - Create project wrapper only if customization required - Auto-authentication with nonce/cookie handling - JSON I/O for AI parsing - Batch testing support - Add to ROADMAP.md as opportunity #9 - Update CHANGELOG.md
1 parent 0abce83 commit 37010be

4 files changed

Lines changed: 733 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11+
- **WP AJAX Test Tool Specification** (`tools/wp-ajax-test/SPEC.md`)
12+
- Lightweight WordPress AJAX endpoint testing without browser automation
13+
- Centralized-by-default design (call from AI-DDTK, local wrapper when needed)
14+
- Auto-authentication with nonce/cookie handling
15+
- JSON I/O for AI agent parsing
16+
- Batch testing support
17+
- AI agent instructions for centralized vs. local copy decision tree
18+
- **ROADMAP.md**: Added AJAX Endpoint Testing as opportunity #9
1119
- **SOLID Principles Guidance** in AGENTS.md (v2.3.1)
1220
- Added to Core Requirements section with full acronym breakdown
1321
- Integrated into "Building from the Ground Up" checklist

‎ROADMAP.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,35 @@ Runtime performance analysis to complement WPCC's static analysis:
122122

123123
---
124124

125+
### 9. **AJAX Endpoint Testing** 📝 Planned
126+
127+
Lightweight WordPress AJAX testing without browser automation:
128+
129+
| Feature | Purpose | AI Orchestration |
130+
|---------|---------|------------------|
131+
| **Direct endpoint testing** | Test wp_ajax_* actions | "Test this AJAX endpoint" workflow |
132+
| **Auto-authentication** | Handle nonces/cookies | Load from `/temp/auth.json` |
133+
| **Batch testing** | Multiple endpoints | Regression testing before deploy |
134+
| **JSON I/O** | Structured output | AI can parse/debug responses |
135+
136+
**Design Principle**: **Centralized by default, local copy when needed**
137+
- AI agents call `~/bin/ai-ddtk/bin/wp-ajax-test` directly
138+
- Create project-specific wrapper only if customization required
139+
- Wrapper calls centralized tool (never duplicate code)
140+
141+
**Status**: Spec drafted in `tools/wp-ajax-test/SPEC.md`
142+
143+
**Key Value**: Fills gap between WPCC (static) and Playwright (heavy E2E). Lightweight integration testing.
144+
145+
**When to use**:
146+
- ✅ Quick AJAX endpoint verification
147+
- ✅ Debugging AJAX failures
148+
- ✅ Regression testing after changes
149+
- ❌ Full browser flows → Use Playwright
150+
- ❌ Load testing → Use Apache Bench
151+
152+
---
153+
125154
## Immediate Next Steps (Low Effort, High Value)
126155

127156
1. ~~**Document the vision**~~ ✅ Added to README (WPCC Advanced Features)

‎tools/wp-ajax-test/AI-INSTRUCTIONS.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# AI Agent Instructions: WP AJAX Test
2+
3+
**For AI agents using wp-ajax-test tool**
4+
5+
---
6+
7+
## Quick Reference
8+
9+
```bash
10+
# Call centrally (recommended)
11+
~/bin/ai-ddtk/bin/wp-ajax-test --url https://site.local --action my_ajax_action --format json
12+
13+
# Create local wrapper (when needed)
14+
cat > test-ajax.sh <<'EOF'
15+
#!/bin/bash
16+
~/bin/ai-ddtk/bin/wp-ajax-test --url "https://site.local" --auth "temp/auth.json" "$@"
17+
EOF
18+
chmod +x test-ajax.sh
19+
echo "test-ajax.sh" >> .gitignore
20+
```
21+
22+
---
23+
24+
## Decision Tree: Centralized vs. Local Copy
25+
26+
```
27+
User Request
28+
│
29+
├─ "Test this AJAX endpoint" ──────────────► Call centrally
30+
│
31+
├─ "Debug AJAX error" ─────────────────────► Call centrally
32+
│
33+
├─ "Test multiple endpoints" ──────────────► Ask: "Create local wrapper + batch file?"
34+
│
35+
├─ "Set up AJAX testing for this project" ─► Create local wrapper
36+
│
37+
└─ Repeated testing needed ────────────────► Create local wrapper
38+
```
39+
40+
---
41+
42+
## When to Call Centrally
43+
44+
**Always prefer centralized calls unless**:
45+
- User explicitly asks for project-specific setup
46+
- Multiple endpoints need testing (batch mode)
47+
- Project has unique auth requirements
48+
- Repeated testing will be needed
49+
50+
**Example**:
51+
```bash
52+
# User: "Test the get_user_data AJAX endpoint"
53+
# AI: Calls centrally
54+
~/bin/ai-ddtk/bin/wp-ajax-test \
55+
--url "https://site.local" \
56+
--action "get_user_data" \
57+
--data '{"user_id": 1}' \
58+
--auth "temp/auth.json" \
59+
--format json
60+
```
61+
62+
---
63+
64+
## When to Create Local Wrapper
65+
66+
**Create wrapper when**:
67+
- User says "set up testing", "create test script", "automate testing"
68+
- Multiple endpoints to test (batch mode)
69+
- Project-specific defaults needed (URL, auth path)
70+
- Repeated testing expected
71+
72+
**Steps**:
73+
1. ✅ Create wrapper script in project root
74+
2. ✅ Add to `.gitignore` immediately
75+
3. ✅ Document in `/temp/README.md` or project README
76+
4. ✅ Use `/temp` for auth files
77+
5. ❌ Never commit wrapper with credentials
78+
6. ❌ Never install wp-ajax-test per-project
79+
80+
**Example**:
81+
```bash
82+
# User: "Set up AJAX testing for this project"
83+
# AI: Creates local wrapper
84+
85+
cat > test-ajax.sh <<'EOF'
86+
#!/bin/bash
87+
# Project-specific AJAX test wrapper
88+
# Calls centralized AI-DDTK tool with defaults
89+
90+
~/bin/ai-ddtk/bin/wp-ajax-test \
91+
--url "https://myproject.local" \
92+
--auth "temp/auth.json" \
93+
"$@"
94+
EOF
95+
96+
chmod +x test-ajax.sh
97+
echo "test-ajax.sh" >> .gitignore
98+
99+
# Document usage
100+
cat >> temp/README.md <<'EOF'
101+
102+
## AJAX Testing
103+
104+
Test endpoints with: ./test-ajax.sh --action <action> --data <json>
105+
106+
Auth file: temp/auth.json (create if missing)
107+
EOF
108+
```
109+
110+
---
111+
112+
## Authentication Handling
113+
114+
### Check for Auth File
115+
116+
```bash
117+
# AI should check first
118+
if [ -f temp/auth.json ]; then
119+
# Use existing auth
120+
~/bin/ai-ddtk/bin/wp-ajax-test --auth temp/auth.json ...
121+
else
122+
# Ask user for credentials
123+
echo "Auth file not found. Need credentials for testing."
124+
fi
125+
```
126+
127+
### Create Auth File (When User Provides Credentials)
128+
129+
```bash
130+
# User provides: username=admin, password=secret123
131+
# AI creates auth file in /temp
132+
133+
cat > temp/auth.json <<'EOF'
134+
{
135+
"username": "admin",
136+
"password": "secret123"
137+
}
138+
EOF
139+
140+
# Add to .gitignore if not already present
141+
grep -q "temp/auth.json" .gitignore || echo "temp/auth.json" >> .gitignore
142+
```
143+
144+
**Never**:
145+
- ❌ Commit auth files
146+
- ❌ Log credentials in verbose output
147+
- ❌ Hardcode credentials in wrapper scripts
148+
149+
---
150+
151+
## Batch Testing
152+
153+
### When to Use Batch Mode
154+
155+
- User wants to test multiple endpoints
156+
- Regression testing before deployment
157+
- Setting up CI/CD tests
158+
159+
### Create Batch File
160+
161+
```bash
162+
# User: "Test all AJAX endpoints in this plugin"
163+
# AI: Creates batch test file
164+
165+
cat > tests/ajax-endpoints.json <<'EOF'
166+
{
167+
"config": {
168+
"url": "https://site.local",
169+
"auth": "temp/auth.json"
170+
},
171+
"tests": [
172+
{
173+
"name": "Get user data",
174+
"action": "get_user_data",
175+
"data": {"user_id": 1},
176+
"expect": {"success": true}
177+
},
178+
{
179+
"name": "Update settings",
180+
"action": "update_settings",
181+
"data": {"setting": "value"},
182+
"expect": {"success": true}
183+
}
184+
]
185+
}
186+
EOF
187+
188+
# Run batch test
189+
~/bin/ai-ddtk/bin/wp-ajax-test --batch tests/ajax-endpoints.json --format json
190+
```
191+
192+
---
193+
194+
## Error Handling
195+
196+
### Common Errors and Responses
197+
198+
| Error Code | AI Response |
199+
|------------|-------------|
200+
| `AUTH_REQUIRED` | "Auth file not found. I'll create temp/auth.json. Please provide credentials." |
201+
| `NONCE_INVALID` | "Nonce expired. Re-authenticating..." (then retry) |
202+
| `ENDPOINT_NOT_FOUND` | "Action 'X' not registered. Check plugin is active and action name is correct." |
203+
| `PERMISSION_DENIED` | "User lacks capability. Try with admin account or check required capability." |
204+
| `TIMEOUT` | "Request timed out. Increase timeout with --timeout 60 or check server performance." |
205+
206+
### Example Error Response
207+
208+
```json
209+
{
210+
"success": false,
211+
"error": {
212+
"code": "NONCE_INVALID",
213+
"message": "Nonce verification failed"
214+
},
215+
"suggestions": [
216+
"Re-authenticate to get fresh nonce",
217+
"Check if user is logged in"
218+
]
219+
}
220+
```
221+
222+
**AI should**:
223+
1. Parse error code
224+
2. Check suggestions array
225+
3. Attempt automatic fix (e.g., re-auth for NONCE_INVALID)
226+
4. Report to user if can't auto-fix
227+
228+
---
229+
230+
## Integration with Other Tools
231+
232+
### WPCC → wp-ajax-test Pipeline
233+
234+
```bash
235+
# 1. WPCC finds AJAX security issue
236+
wpcc --paths plugin/ --format json | grep "ajax"
237+
238+
# 2. AI identifies flagged endpoint
239+
# Finding: "Nonce not verified in my_ajax_action"
240+
241+
# 3. Test endpoint to confirm
242+
~/bin/ai-ddtk/bin/wp-ajax-test \
243+
--url https://site.local \
244+
--action my_ajax_action \
245+
--format json
246+
247+
# 4. Report: "Confirmed: endpoint accepts requests without nonce"
248+
```
249+
250+
---
251+
252+
## Best Practices
253+
254+
1. **Always call centrally first** - Only create local wrapper if needed
255+
2. **Use /temp for auth** - Never commit credentials
256+
3. **JSON output for parsing** - Use `--format json` when AI needs to analyze
257+
4. **Document local wrappers** - Add usage to temp/README.md
258+
5. **Add to .gitignore** - Immediately after creating wrapper
259+
6. **Auto-retry on nonce errors** - Re-authenticate and retry once
260+
7. **Validate before batch** - Test one endpoint before running full batch
261+
262+
---
263+
264+
**See**: `tools/wp-ajax-test/SPEC.md` for complete specification
265+

0 commit comments

Comments
 (0)