# Example Testing Guide

This directory contains comprehensive golden tests for all Flow SDK examples to ensure they remain functional and up-to-date.

## Test Structure

### `test_examples.py`
- Basic validation tests for all examples
- Checks file existence, syntax, and structure
- Validates YAML configurations
- Mock execution tests for core examples

### `test_examples_golden.py`
- Comprehensive golden tests with execution validation
- Tests actual execution paths with proper mocking
- Captures and validates outputs
- Ensures examples handle errors gracefully
- Generates golden output files for comparison

### `validate_examples.py`
- Standalone validation script
- Can be run independently of pytest
- Generates golden outputs for visual inspection
- Provides detailed validation reports

## Running Tests

### Run all example tests:
```bash
pytest tests/test_examples.py -v
pytest tests/test_examples_golden.py -v
```

### Run validation script:
```bash
python tests/validate_examples.py
```

### Generate golden outputs:
```bash
python tests/validate_examples.py --generate-golden
```

### Run specific test:
```bash
pytest tests/test_examples.py::TestExamples::test_verify_instance_example -v
```

## Adding New Examples

When adding a new example:

1. **Follow the pattern**: Examples should have:
   - Module-level docstring with Prerequisites and How to run sections
   - `main()` function
   - `if __name__ == "__main__":` guard
   - Proper error handling

2. **Update tests**: Add the example to:
   - `expected_files` list in `test_examples.py`
   - Add a specific test method if the example has unique behavior

3. **Validate**: Run the validation script to ensure the new example works:
   ```bash
   python tests/validate_examples.py
   ```

## Golden Outputs

Golden outputs are stored in `tests/golden_outputs/` and contain:
- Expected stdout/stderr output
- Exit codes
- Execution metadata

These help ensure examples produce consistent, expected results across updates.

## CI/CD Integration

The `.github/workflows/validate-examples.yml` workflow automatically:
- Runs all example tests on push/PR
- Tests across multiple Python versions
- Generates and uploads golden outputs as artifacts
- Ensures examples stay functional with SDK changes