# MaplePress Plugin Testing Guide

## Prerequisites

- WordPress running at http://localhost:8081
- MaplePress backend running at http://localhost:8000 (or update API URL in settings)
- WordPress admin access

## Test Scenarios

### Scenario 1: Fresh Installation (Activation Flow)

**Steps:**

1. **Deactivate the plugin** (if already activated)
   - Go to WordPress Admin → Plugins
   - Find "MaplePress"
   - Click "Deactivate"

2. **Activate the plugin**
   - Click "Activate" on MaplePress
   - **Expected:** Auto-redirect to Settings → MaplePress

3. **Verify Welcome Screen**
   - **Expected:** See "🚀 Welcome to MaplePress!" banner
   - **Expected:** See 4-step setup instructions
   - **Expected:** See "Sign Up at MaplePress.io" button
   - **Expected:** See "Login to Existing Account" button

4. **Verify Admin Notice** (if you navigate away)
   - Go to Dashboard or any other admin page
   - **Expected:** See yellow warning banner at top
   - **Expected:** Message says "MaplePress Setup Required"
   - **Expected:** Contains links to sign up and configure

### Scenario 2: API Key Entry (Success Path)

**Prerequisites:**
- You have a valid API key from the backend
- To get one:
  ```bash
  # Use the backend API to register and create a site
  # Or use existing test API key
  ```

**Steps:**

1. **Go to Settings → MaplePress**

2. **Verify default API URL**
   - **Expected:** API URL field shows `http://localhost:8000`

3. **Enter a valid API key**
   - Paste your API key in the "API Key" field
   - **Optional:** Check "Enable MaplePress"
   - Click "Save Settings & Verify Connection"

4. **Verify Success Response**
   - **Expected:** Green success message: "✓ API connection verified successfully!"
   - **Expected:** Welcome banner disappears
   - **Expected:** New section appears: "✓ Connected to MaplePress"
   - **Expected:** Site details table shows:
     - Site ID (UUID)
     - Tenant ID (UUID)
     - Domain (your site domain)
     - Plan (e.g., "Free")
     - Status (● Active or ● Inactive)
   - **Expected:** "→ Open MaplePress Dashboard" button appears

5. **Verify Admin Notice Removed**
   - Navigate to Dashboard or Posts
   - **Expected:** Yellow warning banner is GONE

### Scenario 3: Invalid API Key (Error Path)

**Steps:**

1. **Go to Settings → MaplePress**

2. **Enter an invalid API key**
   - Enter: `invalid_key_12345`
   - Click "Save Settings & Verify Connection"

3. **Verify Error Response**
   - **Expected:** Red error message appears
   - **Expected:** Message says "API Connection Error: [error details]"
   - **Expected:** Site details table does NOT appear
   - **Expected:** Plugin status remains "needs setup"

4. **Verify Admin Notice Persists**
   - Navigate to Dashboard
   - **Expected:** Yellow warning banner STILL shows

### Scenario 4: Empty API Key

**Steps:**

1. **Go to Settings → MaplePress**

2. **Leave API key field empty**
   - Click "Save Settings & Verify Connection"

3. **Verify Behavior**
   - **Expected:** No error message (just saves empty)
   - **Expected:** Welcome banner still shows
   - **Expected:** Admin notice persists on other pages

### Scenario 5: API Key Update/Change

**Steps:**

1. **Start with a valid, connected API key**
   - Verify you see "✓ Connected to MaplePress"

2. **Change to a different valid API key**
   - Enter new API key
   - Click "Save Settings & Verify Connection"

3. **Verify Update**
   - **Expected:** Success message appears
   - **Expected:** Site details update to reflect new site

4. **Change to invalid key**
   - Enter invalid key
   - Click save

5. **Verify Validation**
   - **Expected:** Error message appears
   - **Expected:** Connection status changes back to "needs setup"
   - **Expected:** Admin notice returns

## Testing Checklist

- [ ] Plugin activation redirects to settings page
- [ ] Welcome banner shows on first visit
- [ ] "Sign Up" button links to https://getmaplepress.com/register (opens in new tab)
- [ ] "Login" button links to https://getmaplepress.com/login (opens in new tab)
- [ ] Admin notice appears on all pages when not configured
- [ ] Admin notice does NOT appear on settings page itself
- [ ] Admin notice is dismissible
- [ ] Valid API key shows success message
- [ ] Valid API key populates site details correctly
- [ ] Invalid API key shows clear error message
- [ ] Site details table shows after successful connection
- [ ] Site details include: site_id, tenant_id, domain, plan_tier
- [ ] Status indicator shows correct state (Active/Inactive)
- [ ] "Open MaplePress Dashboard" button appears when connected
- [ ] Dashboard button links to https://getmaplepress.com/dashboard (opens in new tab)
- [ ] Admin notice disappears after successful configuration
- [ ] Enable checkbox works correctly
- [ ] Settings persist after save
- [ ] API URL can be changed (for dev vs production)

## Manual API Key Testing

If you need to test with a real API key, follow the backend setup guide:

**See: `cloud/maplepress-backend/GETTING-STARTED.md` → "Create Test Data" section**

Quick summary:
1. Register a user with `POST /api/v1/register`
2. Create a site with `POST /api/v1/sites`
3. Save the `api_key` from the site creation response

For detailed curl examples and full instructions, see the backend GETTING-STARTED.md file.

## Expected Settings Structure

After successful configuration, WordPress options should contain:

```php
array(
  'api_url'      => 'http://localhost:8000',
  'api_key'      => 'live_sk_...',
  'site_id'      => 'abc-123-def',
  'tenant_id'    => 'xyz-456-uvw',
  'domain'       => 'localhost',
  'plan_tier'    => 'free',
  'is_verified'  => true,
  'enabled'      => true,
  'needs_setup'  => false,
)
```

## Troubleshooting

### Plugin doesn't redirect after activation
- Make sure you're not activating multiple plugins at once
- Try deactivating and reactivating
- Check if transient was set: `get_transient('maplepress_activation_redirect')`

### API connection fails
- Verify backend is running: `curl http://localhost:8000/health`
- Check API URL in settings matches backend URL
- Verify API key is correct and not expired
- Check WordPress debug logs: `docker exec -it maple-wordpress-dev tail -f /var/www/html/wp-content/debug.log`
- See backend troubleshooting: `cloud/maplepress-backend/GETTING-STARTED.md`

### Admin notice doesn't disappear
- Verify `needs_setup` is set to `false` in settings
- Clear WordPress transients/cache
- Deactivate and reactivate plugin

### Site details don't show
- Verify API response includes all fields (site_id, tenant_id, domain, plan_tier)
- Check backend `/api/v1/plugin/status` endpoint response
- Enable WordPress debug mode and check for PHP errors

## Success Criteria

✅ User can activate plugin and see setup instructions
✅ User can click external links to sign up/login
✅ User can enter API key and validate it
✅ Valid API key shows success and site details
✅ Invalid API key shows clear error
✅ Admin notices guide user through setup
✅ Connected state shows all site information
✅ Plugin can be enabled/disabled after connection

## Next Steps After Testing

Once basic authentication flow is verified:
1. Test with production backend URL
2. Implement content indexing features
3. Add search widget functionality
4. Build web dashboard for account/site management