upskill-event-manager/docs/hvac-role-testing-plan.md

# HVAC Role Manager Testing Plan

## Overview
This document outlines the simplified approach to testing the HVAC Role Manager in the staging environment, focusing on core role creation and capability management.

## Test Implementation Structure
```mermaid
graph TD
    A[Setup Test Environment] --> B[Create Test Suite]
    B --> C[Implement Tests]
    C --> D[Document & Demonstrate]
    
    subgraph "1. Setup Test Environment"
        A1[Configure vendor PHPUnit] --> A2[Setup bootstrap file]
        A2 --> A3[Configure test paths]
    end
    
    subgraph "2. Create Test Suite"
        B1[Create TestCase class] --> B2[Setup fixtures]
        B2 --> B3[Configure isolation]
    end
    
    subgraph "3. Implement Tests"
        C1[WordPress Capabilities] --> C2[HVAC Capabilities]
        C2 --> C3[Role Management]
    end
    
    subgraph "4. Document & Demonstrate"
        D1[Run tests] --> D2[Generate report]
        D2 --> D3[Create guide]
    end
```

## Implementation Steps

### 1. Test Environment Setup (30 mins)
- Configure vendor PHPUnit
  ```bash
  ./vendor/bin/phpunit --version
  ```
- Setup bootstrap-staging.php
  ```php
  require_once dirname(__DIR__) . '/vendor/autoload.php';
  require_once dirname(__DIR__) . '/vendor/yoast/wp-test-utils/src/WPIntegration/bootstrap.php';
  ```
- Configure test isolation
  ```php
  // In bootstrap-staging.php
  tests_add_filter('muplugins_loaded', function() {
      require dirname(__DIR__) . '/hvac-role-manager.php';
  });
  ```

### 2. Test Suite Creation (45 mins)
```php
class HVAC_Role_Manager_Test extends WP_UnitTestCase {
    protected $role_manager;
    protected $test_role_name = 'hvac_test_trainer';
    
    public function setUp() {
        parent::setUp();
        $this->role_manager = new HVAC_Role_Manager();
    }
    
    public function tearDown() {
        remove_role($this->test_role_name);
        parent::tearDown();
    }
}
```

### 3. Core Tests Implementation (1.5 hours)

#### WordPress Core Capabilities
```php
public function test_wp_core_capabilities() {
    $capabilities = [
        'read' => true,
        'edit_posts' => true,
        'delete_posts' => true
    ];
    
    $role = $this->role_manager->create_role($this->test_role_name, 'Test Trainer', $capabilities);
    $this->assertInstanceOf('WP_Role', $role);
    
    foreach ($capabilities as $cap => $grant) {
        $this->assertTrue($role->has_cap($cap));
    }
}
```

#### HVAC Custom Capabilities
```php
public function test_hvac_capabilities() {
    $capabilities = [
        'manage_hvac_events' => true,
        'view_hvac_reports' => true,
        'edit_hvac_settings' => true
    ];
    
    $role = $this->role_manager->create_role($this->test_role_name, 'Test Trainer', $capabilities);
    $this->assertInstanceOf('WP_Role', $role);
    
    foreach ($capabilities as $cap => $grant) {
        $this->assertTrue($role->has_cap($cap));
    }
}
```

#### Role Management
```php
public function test_role_lifecycle() {
    // Create role
    $role = $this->role_manager->create_role($this->test_role_name, 'Test Trainer');
    $this->assertInstanceOf('WP_Role', $role);
    
    // Modify role
    $this->role_manager->add_capability($this->test_role_name, 'custom_cap');
    $this->assertTrue($role->has_cap('custom_cap'));
    
    // Remove role
    $this->role_manager->remove_role($this->test_role_name);
    $this->assertNull(get_role($this->test_role_name));
}
```

### 4. Documentation & Demonstration (45 mins)

#### Test Execution Script
```bash
#!/bin/bash
# run-role-tests.sh

# Run vendor PHPUnit
./vendor/bin/phpunit \
    --bootstrap tests/bootstrap-staging.php \
    --testsuite role-manager \
    --verbose
```

## Troubleshooting Guide

### Role Creation Issues

#### 1. Role Already Exists
- **Symptom**: Test fails with message "Role 'hvac_test_trainer' already exists"
- **Cause**: Incomplete cleanup from previous test run
- **Solution**: 
  ```php
  public function tearDown() {
      remove_role($this->test_role_name);
      parent::tearDown();
  }
  ```

#### 2. Missing Capabilities
- **Symptom**: Role created but capabilities not assigned
- **Cause**: Incorrect capability array format
- **Solution**:
  ```php
  // Correct format
  $capabilities = [
      'capability_name' => true,  // Grant capability
      'another_cap' => false      // Explicitly deny
  ];
  
  // Incorrect format
  $capabilities = ['capability_name', 'another_cap'];  // Don't use this
  ```

#### 3. Role Assignment Failures
- **Symptom**: User can't access features despite role assignment
- **Cause**: Role not properly assigned or capabilities not refreshed
- **Solution**:
  ```php
  // Proper role assignment
  $user_id = wp_create_user('test_user', 'password', 'test@example.com');
  $user = new WP_User($user_id);
  $user->add_role($this->test_role_name);
  
  // Force capability refresh
  $user = new WP_User($user_id);  // Reload user object
  ```

## Success Criteria
- All test cases pass successfully
- Test coverage includes core WordPress and HVAC capabilities
- Documentation is clear and accessible
- Troubleshooting guide addresses common issues