Why Rust Unit Tests Are Critical for Testing Examples

The Problem

When you have example files that demonstrate language features, you need a way to ensure they:

1. Still compile when the language changes
2. Don't break when refactoring the compiler
3. Stay up-to-date with the current syntax
4. Work correctly (or at least parse correctly)

The Solution: Rust Unit Tests

Why Rust Unit Tests?

1. Automated: Run with cargo test - no manual work
2. Fast: Run in seconds, not minutes
3. Reliable: Same results every time
4. CI/CD Ready: Easy to integrate into GitHub Actions, GitLab CI, etc.
5. Early Detection: Catch breaking changes immediately
6. Documentation: Tests serve as documentation of what works

What We Built

Created tests/example_tests.rs with:

#[test]
fn test_hello_world_demo_parses() {
    let path = Path::new("examples/hello_world_demo.dal");
    if path.exists() {
        test_example_parses(path);
    }
}

#[test]
fn test_all_examples_parse() {
    // Tests ALL examples at once
    // Fails if any example has syntax errors
}

How It Works

1. Parse Tests: Use parse_source() to verify examples compile
2. Execution Tests: Use execute_source() for simple examples
3. Smart Skipping: Automatically skips examples requiring external deps
4. Comprehensive: Tests all examples, not just one at a time

Real Results

When we ran the tests, they immediately caught issues:

❌ Failed to parse 37 example(s):
  - "examples/hello_world_demo.dal": Unexpected character '|' at line 488
  - "examples/cross_chain_patterns.dal": Syntax Error at line 1
  - ...

This is exactly what we want! The tests are:

• ✅ Working correctly
• ✅ Catching real problems
• ✅ Providing actionable feedback

Comparison: Rust Tests vs. Other Approaches

Integration with Development Workflow

For Developers

# Before committing, run:
cargo test example_tests

# If tests pass, examples are valid
# If tests fail, fix the examples before committing

For CI/CD

# .github/workflows/test.yml
- name: Test Examples
  run: cargo test example_tests

For Contributors

When adding a new example:

1. Add it to examples/
2. Add a test in tests/example_tests.rs
3. Run cargo test to verify it works

What Gets Tested

✅ Currently Tested

• Parse Tests: All examples must parse successfully
• Execution Tests: Simple examples (without external deps) must execute
• Comprehensive Test: One test checks all examples at once

🔄 You can contribute:

• Type Checking: Verify types are correct (when type system is complete)
• Semantic Analysis: Check that references are valid
• Output Validation: Compare execution output to expected results
• Performance Tests: Ensure examples run in reasonable time

Example Test Structure

// Individual test for each example
#[test]
fn test_my_example_parses() {
    let path = Path::new("examples/my_example.dal");
    if path.exists() {
        test_example_parses(path);
    }
}

// Comprehensive test for all examples
#[test]
fn test_all_examples_parse() {
    let example_files = get_example_files();
    // ... test all files
}

// Execution test (skips if requires external deps)
#[test]
fn test_simple_examples_execute() {
    // ... test execution for simple examples
}

Benefits Over Manual Testing

Before (Manual)

# Developer has to remember to test
dist_agent_lang run examples/hello_world_demo.dal
dist_agent_lang run examples/smart_contract.dal
# ... 30 more files
# Easy to miss one
# No record of what was tested

After (Automated)

# One command tests everything
cargo test example_tests

# ✅ All examples tested
# ✅ Results recorded
# ✅ Fails if anything breaks
# ✅ Runs in CI automatically

Conclusion

Rust unit tests are the right approach because they:

1. ✅ Catch problems automatically
2. ✅ Integrate with development workflow
3. ✅ Provide fast feedback
4. ✅ Work in CI/CD pipelines
5. ✅ Are maintainable and reliable

The tests we created (tests/example_tests.rs) are already working and catching real issues in the examples. This is exactly what we need to ensure examples stay valid as the language evolves.

Next Steps

1. ✅ Tests Created: tests/example_tests.rs is ready
2. Fix Examples: Update examples that fail to parse
3. Add More Tests: Add execution tests as features are implemented
4. CI Integration: Add to GitHub Actions/GitLab CI
5. Documentation: Keep tests updated as examples are added