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

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

  ./vendor/bin/phpunit --version
  

• Setup bootstrap-staging.php

  require_once dirname(__DIR__) . '/vendor/autoload.php';
  require_once dirname(__DIR__) . '/vendor/yoast/wp-test-utils/src/WPIntegration/bootstrap.php';
  

• Configure test isolation

  // In bootstrap-staging.php
  tests_add_filter('muplugins_loaded', function() {
      require dirname(__DIR__) . '/hvac-role-manager.php';
  });
  

2. Test Suite Creation (45 mins)

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

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

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

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

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

  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:

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

  // 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