api-test-generator

name	api-test-generator
description	Генерация полных Python pytest тестов для REST API эндпоинтов с валидацией схемы. Использовать при создании тестов для новых эндпоинтов, добавлении покрытия для CRUD операций или валидации соответствия API с OpenAPI схемами.
allowed-tools	Bash, Read, Grep, Glob

MikoPBX API Test Generating

Generate comprehensive Python pytest tests for MikoPBX REST API endpoints with full parameter coverage, schema validation, and edge case testing.

What This Skill Does

Analyzes DataStructure.php files and generates complete pytest test suites including:

• ✅ CRUD operation tests (Create, Read, Update, Delete)
• ✅ Positive and negative test cases
• ✅ Parameter validation tests
• ✅ Edge cases and boundary conditions
• ✅ Schema validation tests
• ✅ Proper fixtures and authentication
• ✅ Detailed assertions with error messages

When to Use This Skill

Use this skill when you need to:

• Create pytest tests for new REST API endpoints
• Add comprehensive test coverage for existing endpoints
• Generate tests covering all parameter combinations
• Add schema validation tests for API responses
• Create edge case and negative tests
• Ensure API compliance with OpenAPI specification

Quick Start

Basic Usage

When the user requests test generation:

1. Identify the endpoint

   • API path (e.g., /pbxcore/api/v3/extensions)
   • HTTP methods (GET, POST, PUT, DELETE, PATCH)
   • Resource name (e.g., Extensions)

2. Locate DataStructure.php

   find /Users/nb/PhpstormProjects/mikopbx/Core/src/PBXCoreREST/Lib -name "DataStructure.php" | grep -i "{resource}"
   

3. Analyze parameter definitions Extract from DataStructure.php:

   • Required vs optional parameters
   • Data types and validation rules
   • Default values
   • Enum values
   • Pattern constraints (regex)
   • Min/max values

4. Generate test file Use the complete template from test-template.py

5. Customize for endpoint

   • Replace {ResourceName} placeholders
   • Fill in actual payload structures
   • Add specific field validations
   • Include enum and pattern validations

Test Structure

File Organization

tests/api/
├── test_{resource}_api.py        # Main test file
└── conftest.py                   # Shared fixtures

Test Class Structure

Each test file should have these test classes:

class TestCreate{ResourceName}:
    """Test POST endpoint for creating resources"""
    - test_create_with_valid_data()
    - test_create_missing_required_field()
    - test_create_with_invalid_type()

class TestGet{ResourceName}:
    """Test GET endpoint for retrieving resources"""
    - test_get_all()
    - test_get_by_id()
    - test_get_nonexistent()

class TestUpdate{ResourceName}:
    """Test PUT/PATCH endpoints for updating resources"""
    - test_update_with_valid_data()
    - test_patch_partial_update()

class TestDelete{ResourceName}:
    """Test DELETE endpoint for removing resources"""
    - test_delete_existing()
    - test_delete_nonexistent()

class TestSchemaValidation{ResourceName}:
    """Test response schema validation"""
    - test_response_matches_openapi_schema()

class TestEdgeCases{ResourceName}:
    """Test edge cases and boundary conditions"""
    - test_special_characters_in_fields()
    - test_empty_string_values()
    - test_boundary_values()

Standard Fixtures

@pytest.fixture
def auth_token():
    """Get authentication token"""
    response = requests.post(
        f"{BASE_URL}/pbxcore/api/v3/auth/login",
        json={"login": "admin", "password": "123456789MikoPBX#1"},
        verify=False
    )
    return response.json()["data"]["access_token"]

@pytest.fixture
def headers(auth_token):
    """Standard headers with authentication"""
    return {
        "Authorization": f"Bearer {auth_token}",
        "Content-Type": "application/json"
    }

Common Test Patterns

1. Create with Valid Data

def test_create_with_valid_data(self, headers):
    """Test creating a resource with all valid required parameters"""
    payload = {
        # Based on DataStructure.php
    }

    response = requests.post(
        f"{BASE_URL}{API_PATH}",
        json=payload,
        headers=headers,
        verify=False
    )

    assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.text}"
    data = response.json()
    assert "data" in data
    assert "id" in data["data"]

    # Validate returned values match input
    for key, value in payload.items():
        assert data["data"][key] == value

2. Validation Tests

def test_create_missing_required_field(self, headers):
    """Test validation when required field is missing"""
    payload = {
        # Missing required field
    }

    response = requests.post(
        f"{BASE_URL}{API_PATH}",
        json=payload,
        headers=headers,
        verify=False
    )

    assert response.status_code == 400
    assert "messages" in response.json()

3. Edge Cases

def test_special_characters_in_fields(self, headers):
    """Test handling of special characters"""
    special_chars = "Test <script>alert('xss')</script> & \"quotes\""
    payload = {
        "string_field": special_chars,
    }

    response = requests.post(...)
    assert response.status_code == 200
    assert response.json()["data"]["string_field"] == special_chars

DataStructure Analysis

When analyzing DataStructure.php, extract these key elements:

Parameter Structure

public static function getParameterDefinitions(): array
{
    return [
        'request' => [
            'POST' => [
                'parameter_name' => [
                    'type' => 'string',              // Extract type
                    'description' => 'Description',  // Extract description
                    'example' => 'value',            // Use for test data
                    'required' => true,              // Required vs optional
                    'default' => 'default_value',    // Default value
                    'enum' => ['val1', 'val2'],      // Valid enum values
                    'pattern' => '^[a-z]+$',         // Regex pattern
                    'minLength' => 1,                // Min length
                    'maxLength' => 100,              // Max length
                ],
            ],
        ],
    ];
}

Use This Data To

1. Generate valid payloads - Use example and default values
2. Test required fields - Create tests omitting each required field
3. Test data types - Create tests with wrong types
4. Test enums - Create tests for each enum value and invalid values
5. Test patterns - Create tests for valid/invalid patterns
6. Test boundaries - Create tests for min/max values

Test Documentation Template

Add to the top of each test file:

"""
Tests for {ResourceName} API endpoint

API Endpoint: /pbxcore/api/v3/{resource-path}
DataStructure: src/PBXCoreREST/Lib/{ResourceName}/DataStructure.php

Test Coverage:
- CRUD operations (Create, Read, Update, Delete)
- Required vs optional parameters
- Data type validations
- Enum value validations
- Pattern validations (regex)
- Boundary conditions (min/max values)
- Special characters and edge cases
- Schema validation (when SCHEMA_VALIDATION_STRICT=1)

Requirements:
- pytest
- requests
- Docker container running with MikoPBX

Run tests:
    pytest tests/api/test_{resource_name}.py -v

Run with schema validation:
    # Ensure SCHEMA_VALIDATION_STRICT=1 is set in container
    pytest tests/api/test_{resource_name}.py -v
"""

Output Format

Always generate:

1. ✅ Complete pytest file - Runnable without modifications
2. ✅ Documentation block - Clear description at the top
3. ✅ All test classes - CRUD, schema validation, edge cases
4. ✅ Proper fixtures - Authentication and headers
5. ✅ Clear assertions - With descriptive error messages
6. ✅ Comments - Explaining complex validations

Running Tests

Basic Execution

# Run all API tests
pytest tests/api/ -v

# Run specific endpoint tests
pytest tests/api/test_extensions_api.py -v

# Run specific test class
pytest tests/api/test_extensions_api.py::TestCreateExtensions -v

# Run specific test
pytest tests/api/test_extensions_api.py::TestCreateExtensions::test_create_with_valid_data -v

With Schema Validation

# Enable schema validation in container
docker exec mikopbx_container sh -c 'export SCHEMA_VALIDATION_STRICT=1'

# Run tests
pytest tests/api/test_extensions_api.py -v

Test Markers

# Run only CRUD tests
pytest tests/api/ -m crud -v

# Skip slow tests
pytest tests/api/ -m "not slow" -v

# Run smoke tests
pytest tests/api/ -m smoke -v

Important Notes

MikoPBX-Specific Considerations

• Authentication: All tests need Bearer token from /auth/login
• HTTPS: Use verify=False for self-signed certificates
• Base URL: Default is https://mikopbx-php83.localhost:8445
• Schema validation: Only active when SCHEMA_VALIDATION_STRICT=1 in container
• Container restart: Changes to PHP code require container restart
• Test isolation: Each test should be independent and idempotent

Best Practices

1. ✅ Analyze DataStructure first - Don't guess parameter structures
2. ✅ Include schema validation tests - Only work with SCHEMA_VALIDATION_STRICT=1
3. ✅ Test success and failure cases - Negative tests are critical
4. ✅ Use fixtures for auth - Avoid code duplication
5. ✅ Clean up after tests - Delete created resources in teardown
6. ✅ Document expected behavior - Each test should state what it validates
7. ✅ Use descriptive test names - Clear indication of what's being tested
8. ✅ One assertion per test - Or group related assertions

Additional Resources

Templates

Complete test templates for copy-paste usage:

• test-template.py - Complete pytest template with all test classes
• crud-tests.py - Reusable CRUD operation patterns
• edge-cases.py - Edge case and boundary test patterns

Reference Documentation

• pytest-patterns.md - Pytest patterns, fixtures, and best practices

Quick Reference

Test a new endpoint in 5 steps:

1. Find DataStructure.php
2. Copy test-template.py
3. Replace {ResourceName} and {resource-path}
4. Fill in payloads based on DataStructure
5. Run pytest tests/api/test_{resource}_api.py -v

Need specific patterns?

• CRUD patterns → crud-tests.py
• Edge cases → edge-cases.py
• Pytest best practices → pytest-patterns.md

Example Invocation

User: "Generate pytest tests for the Extensions API endpoint"

Your response should:

1. Find /src/PBXCoreREST/Lib/Extensions/DataStructure.php
2. Read and analyze parameter definitions
3. Use test-template.py as base
4. Generate comprehensive test file with:
   • Valid test data from DataStructure
   • All CRUD operations
   • Edge cases for special characters, boundaries
   • Schema validation tests
5. Save to tests/api/test_extensions_api.py
6. Provide run instructions

Troubleshooting

Common Issues

Issue: Test fails with "Unauthorized" Solution: Check that auth_token fixture is working and token is valid

Issue: Schema validation tests don't run Solution: Ensure SCHEMA_VALIDATION_STRICT=1 is set in container

Issue: Tests are flaky Solution: Ensure test isolation - each test should create its own resources

Issue: Container not accessible Solution: Check container is running: docker ps | grep mikopbx

Issue: SSL certificate errors Solution: Ensure verify=False is set in requests

Debug Commands

# Check container is running
docker ps | grep mikopbx

# Check environment variable
docker exec mikopbx_container env | grep SCHEMA_VALIDATION_STRICT

# View API logs
docker exec mikopbx_container tail -f /storage/usbdisk1/mikopbx/log/php/error.log

# Test API manually
curl -k https://mikopbx-php83.localhost:8445/pbxcore/api/v3/system/ping