care-book-block-ultimate/specs/001-wordpress-plugin-para/quickstart.md

Quickstart Guide: Care Booking Block Plugin

Feature: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare
Date: 2025-09-10
Purpose: End-to-end validation scenarios for testing

Prerequisites Validation

Environment Setup

# 1. WordPress 5.0+ installation
wp core version --allow-root
# Expected: 5.0.0 or higher

# 2. KiviCare plugin active
wp plugin status kivicare --allow-root
# Expected: Status: Active

# 3. PHP version check
php -v
# Expected: PHP 7.4+ 

# 4. Database access
wp db check --allow-root
# Expected: Success

Test Data Setup

-- Ensure test doctors exist in KiviCare
INSERT INTO wp_kc_doctors (id, name, email) VALUES 
(999, 'Test Doctor 1', 'test1@clinic.com'),
(998, 'Test Doctor 2', 'test2@clinic.com');

-- Ensure test services exist
INSERT INTO wp_kc_services (id, name, doctor_id) VALUES
(888, 'Test Service 1', 999),
(887, 'Test Service 2', 999);

Installation & Activation Test

Step 1: Plugin Installation

# Upload plugin to WordPress
cp -r care-booking-block/ /wp-content/plugins/

# Activate plugin via WP-CLI
wp plugin activate care-booking-block --allow-root

Expected Outcome:

• Plugin activates without errors
• Database table wp_care_booking_restrictions created
• Admin menu "Care Booking Control" appears

Validation:

-- Check table creation
DESCRIBE wp_care_booking_restrictions;

-- Check WordPress options
SELECT option_value FROM wp_options WHERE option_name = 'care_booking_plugin_version';

Step 2: Admin Interface Access

# Navigate to admin interface
# URL: /wp-admin/admin.php?page=care-booking-control

Expected Outcome:

• Admin page loads without errors
• List of doctors from KiviCare displayed
• Toggle switches for each doctor visible
• No PHP errors in debug.log

Core Functionality Tests

Test Scenario 1: Block Doctor from Public Booking

User Story: Administrator blocks Dr. Test Doctor 1 from public appointments

Steps:

1. Navigate to Care Booking Control admin page
2. Find "Test Doctor 1" in the list
3. Click toggle to block doctor
4. Save changes

Expected Outcome:

// AJAX Response
{
    "success": true,
    "data": {
        "message": "Restriction updated successfully",
        "restriction": {
            "restriction_type": "doctor",
            "target_id": 999,
            "is_blocked": true
        }
    }
}

Database Validation:

SELECT * FROM wp_care_booking_restrictions 
WHERE restriction_type = 'doctor' AND target_id = 999;
-- Expected: 1 row with is_blocked = 1

Frontend Validation:

// Check if CSS is injected
const hiddenDoctor = document.querySelector('.kivicare-doctor[data-doctor-id="999"]');
const computedStyle = window.getComputedStyle(hiddenDoctor);
console.log(computedStyle.display); // Expected: 'none'

Test Scenario 2: Hide Service for Specific Doctor

User Story: Administrator hides "Test Service 2" for "Test Doctor 1"

Steps:

1. In admin interface, expand "Test Doctor 1" services
2. Find "Test Service 2" checkbox
3. Uncheck to hide service
4. Save changes

Expected Outcome:

// AJAX Response
{
    "success": true,
    "data": {
        "restriction": {
            "restriction_type": "service",
            "target_id": 887,
            "doctor_id": 999,
            "is_blocked": true
        }
    }
}

Frontend Test:

// KiviCare filter test
$services = apply_filters('kc_get_services_by_doctor', [
    ['id' => 888, 'name' => 'Test Service 1'],
    ['id' => 887, 'name' => 'Test Service 2']
], 999);

// Expected: Only Service 1 in array
assert(count($services) === 1);
assert($services[0]['id'] === 888);

Test Scenario 3: Frontend Booking Form Validation

User Story: Patient tries to book appointment and sees filtered options

Steps:

1. Navigate to KiviCare booking form on frontend
2. Open doctor selection dropdown
3. Verify blocked doctors not visible
4. Select remaining doctor
5. Check service options for selected doctor

Expected Outcome:

• Test Doctor 1 (ID: 999) not in dropdown
• Test Doctor 2 (ID: 998) visible and selectable
• When Test Doctor 1 was selected before blocking, only Test Service 1 visible

DOM Validation:

// Check doctor dropdown
const doctorOptions = document.querySelectorAll('#doctor-select option');
const blockedDoctorOption = Array.from(doctorOptions)
    .find(option => option.value === '999');
// Expected: undefined (not found)

// Check CSS injection
const injectedCSS = document.querySelector('style[data-care-booking]');
// Expected: Contains .kivicare-doctor[data-doctor-id="999"] { display: none !important; }

Performance Validation

Response Time Test

# Test admin AJAX endpoints
time curl -X POST "http://site.com/wp-admin/admin-ajax.php" \
  -d "action=care_booking_get_restrictions&nonce=test_nonce"
# Expected: < 200ms

time curl -X POST "http://site.com/wp-admin/admin-ajax.php" \
  -d "action=care_booking_toggle_restriction&nonce=test_nonce&target_id=999&restriction_type=doctor&is_blocked=true"
# Expected: < 300ms

Page Load Impact Test

// Measure frontend page load impact
const startTime = performance.now();
// Load KiviCare booking form page
const loadTime = performance.now() - startTime;
// Expected: < 5% increase over baseline (without plugin)

Cache Validation

// Test cache invalidation
set_transient('care_booking_doctors_blocked', [999], 3600);
// Trigger restriction update
do_action('care_booking_restriction_updated');
// Check cache cleared
$cached = get_transient('care_booking_doctors_blocked');
// Expected: false (cache cleared)

Error Handling Tests

Test Scenario 4: KiviCare Plugin Deactivated

Steps:

1. Deactivate KiviCare plugin
2. Access Care Booking Control admin page
3. Try to access frontend booking form

Expected Outcome:

• Admin page shows warning message
• Frontend continues working without errors
• No fatal PHP errors in debug.log

Test Scenario 5: Database Connection Error

Steps:

1. Temporarily block database access
2. Try to load admin interface
3. Try to toggle restriction

Expected Outcome:

{
    "success": false,
    "data": {
        "message": "Database error occurred. Please try again.",
        "code": "DB_CONNECTION_ERROR"
    }
}

Test Scenario 6: Invalid Nonce

Steps:

1. Send AJAX request with invalid nonce
2. Check response

Expected Outcome:

{
    "success": false,
    "data": {
        "message": "Invalid nonce",
        "code": "INVALID_NONCE"
    }
}

Compatibility Tests

Test Scenario 7: Cache Plugin Compatibility

Setup: Install WP Rocket or W3 Total Cache

Steps:

1. Enable page caching
2. Block a doctor
3. View frontend booking form
4. Check if changes are visible immediately

Expected Outcome:

• Changes visible within cache invalidation timeout
• No cached restrictions shown to users

Test Scenario 8: Theme Compatibility

Setup: Switch to popular WordPress theme

Steps:

1. Activate different theme (Twenty Twenty-Three, Astra, etc.)
2. Test admin interface styling
3. Test frontend CSS injection

Expected Outcome:

• Admin interface maintains WordPress native styling
• Frontend CSS selectors work across themes

Success Criteria Validation

Metrics to Verify

1. 100% restriction compliance: Blocked doctors/services never appear
2. <2 minute configuration: Time administrator to set up restrictions
3. <5% performance impact: Page load time increase
4. Zero critical errors: No fatal errors in debug.log for 24 hours

Final Validation Checklist

• All test scenarios pass
• Performance targets met
• Error handling works correctly
• Compatibility verified
• Success metrics achieved
• Documentation complete

This quickstart guide provides comprehensive validation scenarios to ensure the plugin meets all functional requirements while maintaining system stability.