Initial commit: Site Builder with PHP API backend
Visual drag-and-drop website builder using GrapesJS with: - Multi-page editor with live preview - File-based asset storage via PHP API (no localStorage base64) - Template library, Docker support, and Playwright test suite Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
320
TESTING_GUIDE.md
Normal file
320
TESTING_GUIDE.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# Site Builder - AI Agent Testing Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide provides instructions for AI agents to test the site builder's WHP integration.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. WHP must be installed and running
|
||||
2. Site builder files deployed to WHP
|
||||
3. Valid WHP user account with shell access
|
||||
4. Site builder API endpoint accessible
|
||||
|
||||
## Quick Test (Without Browser)
|
||||
|
||||
### 1. Test API Directly with PHP
|
||||
|
||||
```bash
|
||||
# Create a test script to simulate API calls
|
||||
cat > /tmp/test-site-builder-api.php << 'EOF'
|
||||
<?php
|
||||
// Simulate WHP environment
|
||||
define('AUTH_USER', 'testuser');
|
||||
define('HOME_DIR', '/tmp/testuser-home');
|
||||
|
||||
// Create test directory structure
|
||||
$homeDir = '/tmp/testuser-home';
|
||||
mkdir($homeDir . '/public_html/site-builder/sites', 0755, true);
|
||||
|
||||
// Test data
|
||||
$testSite = [
|
||||
'id' => 'test_' . uniqid(),
|
||||
'name' => 'Test Site from AI',
|
||||
'html' => '<div class="container"><h1>Hello from AI Agent</h1><p>This site was created via API test.</p></div>',
|
||||
'css' => 'body { font-family: Arial; margin: 0; } .container { max-width: 800px; margin: 0 auto; padding: 20px; } h1 { color: #0066cc; }',
|
||||
'created' => time()
|
||||
];
|
||||
|
||||
// Simulate POST data
|
||||
$_SERVER['REQUEST_METHOD'] = 'POST';
|
||||
$_GET['action'] = 'save';
|
||||
file_put_contents('php://input', json_encode($testSite));
|
||||
|
||||
// Include the API (simulate request)
|
||||
echo "Testing save operation...\n";
|
||||
include '/docker/whp/web/api/site-builder.php';
|
||||
|
||||
// Test list operation
|
||||
echo "\n\nTesting list operation...\n";
|
||||
$_SERVER['REQUEST_METHOD'] = 'GET';
|
||||
$_GET['action'] = 'list';
|
||||
include '/docker/whp/web/api/site-builder.php';
|
||||
|
||||
echo "\n\nTest complete. Check $homeDir/public_html/site-builder/sites/\n";
|
||||
EOF
|
||||
|
||||
# Run the test
|
||||
php /tmp/test-site-builder-api.php
|
||||
```
|
||||
|
||||
### 2. Test with curl (Requires WHP Session)
|
||||
|
||||
```bash
|
||||
# First, log into WHP and extract session ID
|
||||
# This is a simplified example - actual session extraction varies
|
||||
|
||||
# Test list endpoint
|
||||
curl 'http://localhost/api/site-builder.php?action=list' \
|
||||
-H 'Cookie: PHPSESSID=your_session_id' \
|
||||
-v
|
||||
|
||||
# Test save endpoint
|
||||
curl 'http://localhost/api/site-builder.php?action=save' \
|
||||
-X POST \
|
||||
-H 'Cookie: PHPSESSID=your_session_id' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"name": "AI Test Site",
|
||||
"html": "<h1>Test from curl</h1>",
|
||||
"css": "h1 { color: red; }"
|
||||
}' \
|
||||
-v
|
||||
```
|
||||
|
||||
## File System Verification
|
||||
|
||||
```bash
|
||||
# Check that directories were created
|
||||
ls -la /home/testuser/public_html/site-builder/sites/
|
||||
|
||||
# Verify JSON file format
|
||||
cat /home/testuser/public_html/site-builder/sites/*.json | jq .
|
||||
|
||||
# Verify HTML output
|
||||
cat /home/testuser/public_html/site-builder/sites/*.html
|
||||
|
||||
# Check file permissions
|
||||
ls -l /home/testuser/public_html/site-builder/sites/
|
||||
# Should show: -rw-r--r-- for files, drwxr-xr-x for directories
|
||||
```
|
||||
|
||||
## Integration Test Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Complete integration test for site builder
|
||||
|
||||
echo "=== Site Builder Integration Test ==="
|
||||
echo ""
|
||||
|
||||
# 1. Deploy API
|
||||
echo "[1/5] Deploying API to WHP..."
|
||||
cp /home/jknapp/code/whp/web-files/api/site-builder.php /docker/whp/web/api/
|
||||
echo "✓ API deployed"
|
||||
|
||||
# 2. Deploy frontend
|
||||
echo "[2/5] Deploying frontend..."
|
||||
mkdir -p /docker/whp/web/site-builder
|
||||
cp -r /home/jknapp/code/site-builder/* /docker/whp/web/site-builder/
|
||||
echo "✓ Frontend deployed"
|
||||
|
||||
# 3. Test API endpoint existence
|
||||
echo "[3/5] Testing API endpoint..."
|
||||
if [ -f /docker/whp/web/api/site-builder.php ]; then
|
||||
echo "✓ API file exists"
|
||||
else
|
||||
echo "✗ API file not found!"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 4. Test directory creation
|
||||
echo "[4/5] Testing directory structure..."
|
||||
TEST_USER="testuser"
|
||||
TEST_HOME="/tmp/test-whp-user"
|
||||
mkdir -p $TEST_HOME/public_html
|
||||
|
||||
# Simulate API call (simplified)
|
||||
echo "✓ Directory structure ready"
|
||||
|
||||
# 5. Test frontend files
|
||||
echo "[5/5] Checking frontend files..."
|
||||
required_files=(
|
||||
"/docker/whp/web/site-builder/index.html"
|
||||
"/docker/whp/web/site-builder/js/editor.js"
|
||||
"/docker/whp/web/site-builder/js/whp-integration.js"
|
||||
"/docker/whp/web/site-builder/css/editor.css"
|
||||
)
|
||||
|
||||
for file in "${required_files[@]}"; do
|
||||
if [ -f "$file" ]; then
|
||||
echo "✓ Found: $file"
|
||||
else
|
||||
echo "✗ Missing: $file"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== All Tests Passed ==="
|
||||
echo ""
|
||||
echo "Access the site builder at:"
|
||||
echo " http://your-whp-domain.com/site-builder/"
|
||||
echo ""
|
||||
echo "API endpoint:"
|
||||
echo " http://your-whp-domain.com/api/site-builder.php"
|
||||
```
|
||||
|
||||
## Manual Browser Testing (For Human Users)
|
||||
|
||||
1. **Access Site Builder**
|
||||
- Navigate to `http://localhost/site-builder/`
|
||||
- Should see GrapesJS editor interface
|
||||
|
||||
2. **Create a Test Page**
|
||||
- Drag a "Section" block onto the canvas
|
||||
- Add a "Text" block
|
||||
- Type some content
|
||||
- Apply some styling
|
||||
|
||||
3. **Test Save**
|
||||
- Click the "Save" button in toolbar
|
||||
- Enter a site name
|
||||
- Should see success notification
|
||||
|
||||
4. **Verify Save**
|
||||
- Check `~/public_html/site-builder/sites/`
|
||||
- Should contain `.json` and `.html` files
|
||||
|
||||
5. **Test Load**
|
||||
- Click "Load" button
|
||||
- Should see your saved site in the list
|
||||
- Click "Load" on the site
|
||||
- Should restore the editor state
|
||||
|
||||
6. **Test Published HTML**
|
||||
- Open the generated `.html` file in browser
|
||||
- Should see your page without the editor
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: "Not authenticated" Error
|
||||
|
||||
**Cause:** API is not receiving WHP session data
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check that auto-prepend.php is loading
|
||||
grep "auto_prepend_file" /etc/php/*/fpm/php.ini
|
||||
|
||||
# Verify WHP session
|
||||
# Log into WHP first, then test API
|
||||
```
|
||||
|
||||
### Issue: Directory Permission Denied
|
||||
|
||||
**Cause:** PHP doesn't have write access to user home directory
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check directory ownership
|
||||
ls -la ~/public_html/site-builder
|
||||
|
||||
# Fix permissions if needed
|
||||
chmod 755 ~/public_html/site-builder
|
||||
```
|
||||
|
||||
### Issue: JSON Parse Error
|
||||
|
||||
**Cause:** Invalid JSON being sent to API
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Test JSON validity
|
||||
echo '{"name":"test","html":"<h1>test</h1>"}' | jq .
|
||||
|
||||
# Check request payload in browser dev tools
|
||||
```
|
||||
|
||||
## Automated Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
bash /home/jknapp/code/site-builder/run-tests.sh
|
||||
|
||||
# Expected output:
|
||||
# ✓ API deployed
|
||||
# ✓ Frontend deployed
|
||||
# ✓ Directory structure created
|
||||
# ✓ Save operation successful
|
||||
# ✓ Load operation successful
|
||||
# ✓ Delete operation successful
|
||||
# ✓ All tests passed
|
||||
```
|
||||
|
||||
## Test Cleanup
|
||||
|
||||
```bash
|
||||
# Remove test data
|
||||
rm -rf /tmp/testuser-home
|
||||
rm -rf /tmp/test-site-builder*
|
||||
|
||||
# Reset production (if needed)
|
||||
# BE CAREFUL - this deletes all user sites!
|
||||
# rm -rf /home/*/public_html/site-builder/sites/*
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ API endpoints respond correctly (200 OK for valid requests)
|
||||
✅ JSON/HTML files are created in user's directory
|
||||
✅ Files have correct permissions (readable by web server)
|
||||
✅ Save/Load/Delete operations work correctly
|
||||
✅ Auto-save doesn't interfere with manual operations
|
||||
✅ Multiple sites can be managed per user
|
||||
✅ No cross-user data access
|
||||
|
||||
## Next Steps After Testing
|
||||
|
||||
1. Deploy to production WHP instance
|
||||
2. Create user documentation
|
||||
3. Add site builder link to WHP control panel
|
||||
4. Set up backup for user sites
|
||||
5. Monitor error logs for issues
|
||||
6. Gather user feedback
|
||||
|
||||
## AI Agent Testing Workflow
|
||||
|
||||
As an AI agent, I can test this by:
|
||||
|
||||
1. **Deploying files:**
|
||||
```bash
|
||||
cp /home/jknapp/code/whp/web-files/api/site-builder.php /docker/whp/web/api/
|
||||
cp -r /home/jknapp/code/site-builder/* /docker/whp/web/site-builder/
|
||||
```
|
||||
|
||||
2. **Creating a test user directory:**
|
||||
```bash
|
||||
mkdir -p /tmp/ai-test-user/public_html/site-builder/sites
|
||||
```
|
||||
|
||||
3. **Simulating API calls:**
|
||||
```php
|
||||
<?php
|
||||
define('AUTH_USER', 'aitest');
|
||||
define('HOME_DIR', '/tmp/ai-test-user');
|
||||
$_GET['action'] = 'save';
|
||||
// ... test save operation
|
||||
```
|
||||
|
||||
4. **Verifying output:**
|
||||
```bash
|
||||
ls -la /tmp/ai-test-user/public_html/site-builder/sites/
|
||||
cat /tmp/ai-test-user/public_html/site-builder/sites/*.json
|
||||
```
|
||||
|
||||
5. **Reporting results:**
|
||||
- List any errors encountered
|
||||
- Verify all files were created
|
||||
- Confirm permissions are correct
|
||||
- Document any missing features
|
||||
Reference in New Issue
Block a user