Terrace/test/README.md

Unified Test Harness for Terrace

This directory contains the unified test harness for all Terrace language implementations. The harness automatically discovers and runs tests across all supported languages: JavaScript, C, Python, Go, and Rust.

Features

• Cross-language testing: Run the same tests across all language implementations
• Automatic test discovery: Finds all .tce test files in the project
• Flexible test definitions: Tests are defined in human-readable .tce files
• Build integration: Automatically builds required binaries (C test runner)
• Comprehensive reporting: Detailed test results with pass/fail status

Test File Format

Test files use the Terrace format with the following structure:

#schema test

describe Test Suite Name
 it Test description
  key test-key
  packages js c python go rust
  input
   test input data
   more input lines
  output
   expected output line 1
   expected output line 2

Fields

• describe: Defines a test suite
• it: Defines a test case
• key: The test identifier passed to language implementations
• packages: Space-separated list of packages to test (js, c, python, go, rust)
• input: Test input data (optional)
• output: Expected output (optional for Go/Rust which use different testing frameworks)

Usage

Run all tests

npm test
# or
npm run test:unified

Run specific test

node test/test-runner.js <test-key>

Run tests for specific packages

PACKAGES="js python" node test/test-runner.js <test-key>

Supported Test Keys

JavaScript

• linedata:basic - Basic line data parsing
• linedata:tabs - Tab-based indentation
• linedata:head-tail - Head/tail parsing
• new-api:basic - Basic new API functionality
• new-api:hierarchical - Hierarchical document parsing
• new-api:functional - Functional API features
• new-api:node-methods - Node method testing
• new-api:inconsistent-indentation - Arbitrary nesting

C

• linedata:basic - Basic line data parsing
• linedata:tabs - Tab-based indentation
• linedata:head-tail - Head/tail parsing
• new-api:basic - Basic new API functionality
• new-api:hierarchical - Hierarchical document parsing
• new-api:string-views - String view functionality
• new-api:legacy-compat - Legacy API compatibility

Python

• linedata:basic - Basic line data parsing
• linedata:tabs - Tab-based indentation
• linedata:head-tail - Head/tail parsing
• new-api:basic - Basic new API functionality
• new-api:hierarchical - Hierarchical document parsing
• new-api:functional - Functional API features
• new-api:node-methods - Node method testing
• new-api:readers - Reader utilities

Go

• TestTerraceDocument - Document parsing tests
• TestTerraceNode - Node functionality tests

Rust

• test_basic_parsing - Basic parsing functionality
• test_navigation_methods - Navigation and traversal

Adding New Tests

1. Create a new .tce file in the test/ directory or modify existing ones
2. Define test suites and cases using the Terrace format
3. Specify which packages should run the test
4. Add the test key to the appropriate language implementation's test runner
5. Update the supports array in test-runner.js if needed

Test Output Format

Each language implementation should output test results in a consistent format for comparison. The expected format varies by test type:

• LineData tests: | level X | indent Y | offsetHead Z | offsetTail W | line TEXT |
• New API tests: | level X | head "HEAD" | tail "TAIL" | content "CONTENT" |
• Node method tests: Node: head="HEAD", tail="TAIL", isEmpty=BOOL, is(NAME)=BOOL
• Go/Rust tests: Simple "Test passed" message

Integration with CI/CD

The test harness is designed to work with CI/CD systems:

• Returns exit code 0 on success, 1 on failure
• Provides detailed output for debugging
• Can be run in parallel across different environments
• Supports selective test execution

Dependencies

The test harness requires:

• Node.js for the test runner
• Build tools for each language (make, go, cargo, etc.)
• All language implementations to be properly set up

Troubleshooting

Common Issues

1. C tests fail: Ensure the C test runner is built with make in packages/c/
2. Go tests fail: Ensure Go modules are properly initialized
3. Rust tests fail: Ensure Cargo dependencies are installed
4. Python tests fail: Ensure Python dependencies are installed
5. Test discovery fails: Check that .tce files have correct syntax

Debug Mode

Run with verbose output:

DEBUG=1 node test/test-runner.js