# Compliance Testing Guide

## Overview

ai4gh includes compliance test suites for validating GA4GH server implementations. Each suite tests the required endpoints and response formats defined by the corresponding GA4GH specification.

## Running Tests

### Basic Usage

```bash
# Test a Beacon server
ai4gh test beacon https://beacon.example.org

# Test a DRS server
ai4gh test drs https://drs.example.org
```

### Output Formats

```bash
# Text output (default)
ai4gh test beacon https://beacon.example.org

# JSON report
ai4gh test beacon https://beacon.example.org --format json

# HTML report
ai4gh test beacon https://beacon.example.org --format html -o report.html

# JUnit XML (for CI integration)
ai4gh test beacon https://beacon.example.org --format junit -o results.xml
```

### List Available Suites

```bash
ai4gh list-specs
```

## Available Suites

| Suite | Spec | Tests |
|-------|------|-------|
| `beacon` | Beacon v2.0 | info, service-info, map, configuration, filtering_terms, individuals |
| `drs` | DRS v1.4 | service-info, get_object, type validation, content-type |
| `wes` | WES v1.1 | service-info, list_runs, response format |
| `tes` | TES v1.1 | service-info, list_tasks, response format |
| `trs` | TRS v2.0.1 | service-info, tool_classes, tools |
| `htsget` | htsget v1.3 | reads endpoint, variants endpoint, content-type |
| `refget` | refget v2.0 | service-info, sequence lookup, metadata |

## CI Integration

### GitHub Actions

```yaml
- name: Run GA4GH compliance tests
  run: |
    ai4gh test beacon ${{ env.BEACON_URL }} --format junit -o beacon-results.xml
    ai4gh test drs ${{ env.DRS_URL }} --format junit -o drs-results.xml

- name: Publish Test Results
  uses: EnricoMi/publish-unit-test-result-action@v2
  with:
    files: "*-results.xml"
```

## Writing Custom Suites

Extend `ComplianceSuite` and use the `@register_suite` decorator:

```python
from ai4gh.compliance.runner import (
    ComplianceSuite,
    TestResult,
    TestStatus,
    register_suite,
)

@register_suite("my-spec")
class MySpecSuite(ComplianceSuite):
    spec_name = "my-spec"
    spec_version = "1.0.0"

    async def test_health(self) -> TestResult:
        import httpx
        async with httpx.AsyncClient() as client:
            resp = await client.get(f"{self.base_url}/health")
        if resp.status_code == 200:
            return TestResult(name="test_health", status=TestStatus.PASS, spec=self.spec_name)
        return TestResult(
            name="test_health",
            status=TestStatus.FAIL,
            message=f"Expected 200, got {resp.status_code}",
            spec=self.spec_name,
        )
```
