# Wasot Syntax Test Migration Tutorial

## Overview

This document provides a complete guide for systematically transferring test cases from an exhaustive reference list to the main syntax test suite. The process ensures comprehensive test coverage while maintaining accuracy and consistency.

## Background

The Wasot project has:
- **Main test file**: `tests/wasot_syntax_tests.md` - Markdown-based test specifications
- **Exhaustive reference**: `reports/wasot_syntax_exhaustive_cases.md` - Complete list of test case ideas
- **Working file**: `tests/wasot_syntax_exhaustive_cases__working.md` - Copy for tracking progress
- **Generated tests**: `tests/generated_syntax_tests.rs` - Auto-generated Rust tests
- **Test runner**: `scripts/test_syntax.sh` - Validates all tests

## The Iteration Process

Each iteration follows these exact steps:

### Step 1: Planning (TodoWrite)
Always start by updating your todo list to track the iteration:

```
TodoWrite with:
- Iteration X: [Category Name] (15 tests) - in_progress
- Select 15 test cases for iteration X - pending
- Add test cases to syntax tests - pending  
- Generate YAML expectations - pending
- Verify tests pass - pending
- Remove transferred cases from working file - pending
```

### Step 2: Select Test Cases
Choose 15 specific test cases from the working file based on the iteration theme:

**Example themes used:**
- Iteration 11: Document Structure & Line Types
- Iteration 12: Block Nesting & Meta-Line Fundamentals  
- Iteration 13: Special Block Types & Unicode Types
- etc.

Mark the selection task as completed in TodoWrite.

### Step 3: Add Tests to Main File
Add the 15 test cases to `tests/wasot_syntax_tests.md` using this exact format:

```markdown
---

**Test Name**

Brief description of what this test validates.

```wasot
.example
Test input here.
```

```yaml
- block-started:
    type: example
    level: 1
- text-finished:
    lines: ["Test input here."]
- block-finished
```
```

**Critical Requirements:**
- Each test MUST have unique name (no duplicates)
- YAML expectations must be accurate (verify with `to-yaml-test`)
- Follow exact indentation and formatting
- Use `---` separators between tests

Mark this task as completed in TodoWrite.

### Step 4: Generate Accurate YAML Expectations

**NEVER guess YAML output.** Always verify with the actual parser:

```bash
# Create test file
echo "test content" > /tmp/test_case.wasot

# Get actual parser output  
cargo run --bin wasot -- to-yaml-test /tmp/test_case.wasot
```

For complex cases, test multiple scenarios to understand parser behavior.

**Common pitfalls to avoid:**
- Self-closing blocks may not actually self-close in all contexts
- Deep nesting has reasonable limits (parser panics at ~12+ levels)
- Text between nesting levels affects event ordering
- Block closing order follows implicit rules

Mark this task as completed in TodoWrite.

### Step 5: Verify All Tests Pass

Run the complete test suite:

```bash
./scripts/test_syntax.sh
```

**If tests fail:**
1. Use `to-yaml-test` to get correct output for failing cases
2. Update the YAML expectations in the test file
3. Re-run tests until all pass
4. NEVER proceed with failing tests

The output shows total test count (should increase by 15 each iteration).

Mark this task as completed in TodoWrite.

### Step 6: Clean Up Working File

Remove transferred test cases from `tests/wasot_syntax_exhaustive_cases__working.md`:

```markdown
# Change this:
### Category Name
- Test case 1
- Test case 2  
- Test case 3

# To this:
### Category Name
(All transferred)
```

Use specific text replacement to avoid affecting other sections.

Mark this task as completed, then mark the entire iteration as completed in TodoWrite.

## File Structure & Tools

### Key Files
- `tests/wasot_syntax_tests.md` - Main test specifications (Markdown)
- `tests/wasot_syntax_exhaustive_cases__working.md` - Progress tracking
- `tests/generated_syntax_tests.rs` - Auto-generated Rust tests
- `scripts/test_syntax.sh` - Test runner

### Essential Commands
```bash
# Generate YAML expectations
cargo run --bin wasot -- to-yaml-test file.wasot

# Run all syntax tests  
./scripts/test_syntax.sh

# Count current tests
grep -c "^\*\*.*\*\*$" tests/wasot_syntax_tests.md
```

### Test File Format
```markdown
**Test Name**

Description here.

```wasot
.input
Content here.
```

```yaml
- expected-events-here
```

---
```

## Progress Tracking

### Current Status (as of writing)
- **Total tests**: 150
- **Completed iterations**: 12 (11-12)
- **Remaining iterations**: 8 (13-20)
- **Target**: 285 total tests (150 current + 135 more)

### Iteration Plan
1. **Iteration 11**: Document Structure & Line Types ✅
2. **Iteration 12**: Block Nesting & Meta-Line Fundamentals ✅
3. **Iteration 13**: Special Block Types & Unicode Types
4. **Iteration 14**: Inline Text Variations
5. **Iteration 15**: Parameter Separators & Arguments
6. **Iteration 16**: Advanced ID Handling
7. **Iteration 17**: Text Content & Block Children
8. **Iteration 18**: Links & Footnotes
9. **Iteration 19**: Parser Internals & Tokenization
10. **Iteration 20**: Edge Cases & Parser Resilience

## Common Issues & Solutions

### Duplicate Test Names
**Problem**: Tests fail compilation due to duplicate names
**Solution**: Ensure every test has a unique name, even if similar content

### Incorrect YAML Expectations
**Problem**: Tests fail because expected events don't match actual parser output
**Solution**: Always use `to-yaml-test` to verify expectations

### Parser Limits
**Problem**: Very deep nesting causes parser panics
**Solution**: Use reasonable nesting depth (6-8 levels max)

### Self-Closing Blocks
**Problem**: Assumed self-closing behavior doesn't match parser
**Solution**: Test actual behavior - many blocks aren't truly self-closing

### Block Closing Order
**Problem**: Misunderstanding when blocks close implicitly
**Solution**: Test with `to-yaml-test` to see actual closing sequence

## Quality Standards

### Every Test Must Have:
1. **Unique name** - No duplicates across entire test suite
2. **Clear description** - Explains what syntax feature is being tested
3. **Valid Wasot input** - Follows actual Wasot syntax rules
4. **Accurate YAML expectations** - Verified with actual parser output
5. **Proper formatting** - Consistent indentation and structure

### Test Coverage Goals:
- **Comprehensive**: Cover all major syntax features
- **Edge cases**: Include boundary conditions and error cases
- **Real-world**: Use realistic examples that users might write
- **Progressive**: Build from simple to complex cases

## Handoff Information

### To Continue This Work:

1. **Check current progress**: Look at todo list and test count
2. **Identify next iteration**: Follow the planned sequence (13-20)
3. **Select test cases**: Choose 15 from the working file for the iteration theme
4. **Follow the 6-step process**: Exactly as documented above
5. **Maintain quality**: Always verify with `to-yaml-test`
6. **Track progress**: Update TodoWrite at each step

### Files to Monitor:
- `tests/wasot_syntax_tests.md` - Main test file (should grow by 15 tests per iteration)
- `tests/wasot_syntax_exhaustive_cases__working.md` - Progress tracking (sections marked as transferred)
- Test output - Should always show "X passed; 0 failed"

### Key Success Metrics:
- All tests pass every iteration
- Test count increases by exactly 15 per iteration
- Working file sections get marked as "(All transferred)"
- No duplicate test names
- YAML expectations match actual parser behavior

## Example: Iteration 12 Walkthrough

### 1. TodoWrite Setup
```
Iteration 12: Block Nesting & Meta-Line Fundamentals (15 tests) - in_progress
```

### 2. Selected Test Cases
- Root level implicit block
- Single nesting pattern  
- Deep nesting sequential levels
- Mixed nesting with level skips
- Complex nesting patterns
- (10 more related to nesting...)

### 3. Added Tests
Each test added to main file with format:
```markdown
**Single nesting pattern**

Test basic parent-child nesting relationship.

```wasot
.parent
Parent content.
..child
Child content.
```

```yaml
- block-started:
    type: parent
    level: 1
- text-finished:
    lines: ["Parent content."]
- block-started:
    type: child
    level: 2
- text-finished:
    lines: ["Child content."]
- block-finished
- block-finished
```
```

### 4. Verified with Parser
```bash
echo ".parent\nParent content.\n..child\nChild content." > /tmp/test.wasot
cargo run --bin wasot -- to-yaml-test /tmp/test.wasot
# Output matched expectations
```

### 5. Tests Passed
```bash
./scripts/test_syntax.sh
# Result: 150 passed; 0 failed
```

### 6. Updated Working File
```markdown
### Block Nesting
(All transferred)
```

## Conclusion

This systematic approach ensures high-quality, comprehensive test coverage while maintaining consistency and accuracy. Each iteration adds exactly 15 well-tested cases, building toward complete coverage of Wasot syntax features.

The key to success is:
1. **Never skip the verification step** - Always use `to-yaml-test`
2. **Follow the exact format** - Consistency is critical
3. **Track progress meticulously** - Use TodoWrite religiously
4. **Test thoroughly** - All tests must pass before proceeding

With this process, another AI can seamlessly continue the work and complete the remaining 8 iterations to reach the target of 285 total tests.