# Wasot Syntax Integration Test Plan

## Overview

This report outlines the design and implementation plan for a markdown-based integration test runner for the Wasot markup language. The test framework will parse test definitions from markdown files and verify that Wasot input produces the expected event stream.

## Test File Format

### Structure

The test file (`tests/wasot_syntax_tests.md`) will use the following format:

```markdown
**test name**

Description of what this test is verifying.

```wasot
.paragraph
This is example content
```

```yaml
- block-started:
    type: paragraph
    level: 1
    id: ""
- text-finished:
    lines: ["This is example content"]
- block-finished
```
```

### Key Components

1. **Test Name**: Defined as `**test name**` in bold
2. **Description**: Plain text explaining the test purpose
3. **Input**: Wasot code block containing the input markup
4. **Expected Events**: YAML block containing simplified event representations

## Event Representation Design

Based on the analysis of `src/events/events.rs`, the event types are:

```rust
enum Event {
    BlockStarted { meta_line: MetaLine },
    BlockFinished,
    TextFinished { lines: Vec<String>, links: Vec<Vec<Link>>, footnotes: Vec<Footnote> }
}
```

### Simplified YAML Format

To make tests easier to write, the YAML format will flatten nested structures:

```yaml
# BlockStarted event
- block-started:
    type: "paragraph"           # meta_line.type_name
    level: 1                     # meta_line.level
    id: "optional-id"           # meta_line.id.value
    inline-text: "text"         # meta_line.inline_text.content
    args: ["arg1", "arg2"]      # meta_line.arguments.args
    kwargs:                     # meta_line.arguments.kwargs
      key1: "value1"
      key2: "value2"

# TextFinished event
- text-finished:
    lines: ["line 1", "line 2"]
    links:                      # Optional, only if links exist
      - line: 0
        links:
          - name: "link text"
            target: "http://example.com"
            start: 5
            length: 10
    footnotes:                  # Optional, only if footnotes exist
      - marker: 1
        link: "http://example.com"

# BlockFinished event
- block-finished
```

## Implementation Architecture

### 1. Test Case Structure

```rust
struct TestCase {
    name: String,
    description: String,
    input: String,
    expected_events: Vec<ExpectedEvent>,
}

enum ExpectedEvent {
    BlockStarted {
        type_name: String,
        level: usize,
        id: Option<String>,
        inline_text: Option<String>,
        args: Vec<String>,
        kwargs: HashMap<String, String>,
    },
    TextFinished {
        lines: Vec<String>,
        links: Option<Vec<LinkInfo>>,
        footnotes: Option<Vec<FootnoteInfo>>,
    },
    BlockFinished,
}
```

### 2. Markdown Parser

The parser will need to:

1. **Scan for test markers**: Find all `**test name**` patterns
2. **Extract components**: 
   - Test name from the bold text
   - Description from text before first code block
   - Input from ```wasot code block
   - Expected events from ```yaml code block
3. **Parse YAML**: Convert YAML to `ExpectedEvent` structures
4. **Handle edge cases**: Multiple tests, missing sections, malformed YAML

### 3. Test Runner

```rust
struct IntegrationTestRunner {
    test_file: PathBuf,
    tests: Vec<TestCase>,
}

impl IntegrationTestRunner {
    fn load_tests(&mut self) -> Result<()> {
        // Parse markdown file
        // Extract all test cases
    }
    
    fn run_test(&self, test: &TestCase) -> TestResult {
        // 1. Create WasotParser with test.input
        // 2. Collect all events
        // 3. Compare with test.expected_events
        // 4. Return success/failure with details
    }
    
    fn run_all(&self) -> TestSummary {
        // Run all tests
        // Collect results
        // Generate summary
    }
}
```

### 4. Event Comparison

The comparison logic needs to:

1. **Match event types**: Ensure actual and expected events have same type
2. **Compare fields**: Check all specified fields match
3. **Handle optionals**: Only check fields present in expected events
4. **Provide detailed errors**: Show exactly what didn't match

## Integration Points

### Existing Code to Reuse

1. **WasotParser**: From `src/emitters/parser/` for parsing input
2. **Event types**: From `src/events/events.rs`
3. **Test infrastructure**: Patterns from `src/tests.rs` and `tests/roundtrip_tests.rs`

### New Components Needed

1. **Markdown parser**: Extract test cases from markdown
2. **YAML to ExpectedEvent converter**: Parse YAML into test structures
3. **Event matcher**: Compare actual vs expected events
4. **Test runner binary**: Execute tests and report results

## Implementation Steps

1. **Create test runner module** in `tests/integration/`
2. **Implement markdown parser** using regex or a markdown library
3. **Build YAML parser** for expected events
4. **Create event comparison logic** with detailed error reporting
5. **Add test runner binary** or integrate with existing test harness
6. **Write initial test cases** covering basic Wasot syntax
7. **Add CI integration** to run tests automatically

## Benefits

1. **Readable tests**: Markdown format is easy to read and write
2. **Comprehensive coverage**: Can test all Wasot syntax features
3. **Clear expectations**: YAML format clearly shows expected events
4. **Easy debugging**: Detailed comparison output helps fix issues
5. **Documentation**: Tests serve as syntax examples

## Example Test Cases to Include

1. **Basic blocks**: Single-level blocks with text
2. **Nested blocks**: Multi-level nesting
3. **Inline text**: Blocks with `..` inline text
4. **Arguments**: Positional and keyword arguments
5. **IDs**: Block IDs with `:id` syntax
6. **Links**: Text with embedded links
7. **Footnotes**: Text with footnote markers
8. **Edge cases**: Empty blocks, special characters, escaping

## Conclusion

This integration test framework will provide a robust way to verify Wasot parser behavior while keeping tests maintainable and readable. The markdown format makes it easy for contributors to add new test cases, and the simplified YAML format reduces boilerplate while maintaining clarity about expected behavior.