monorepo/native/wordpress/maplepress-plugin/TESTING.md

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:

  # 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:

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