hedl-test

Shared test fixtures and utilities for HEDL—comprehensive test data, builders, and error cases for consistent testing across all crates.

Testing format converters requires representative documents. Building test cases by hand is tedious and error-prone. Common test scenarios should be reusable across crates. Edge cases need systematic coverage. Error conditions must be validated consistently.

hedl-test provides 15 pre-built fixtures covering all HEDL features, 4 builder types for programmatic document construction, comprehensive error fixtures (15 invalid HEDL, 15 invalid expressions, 8 semantic violations), and edge case generators (deep nesting, wide documents, long strings, many references).

What's Implemented

Comprehensive test infrastructure:

1. 15 Pre-Built Fixtures: Scalars, special strings, references, expressions, tensors, named values, user list, mixed type list, with references, with nest, deep nest, edge cases, comprehensive, blog, empty
2. 4 Builder Types: DocumentBuilder, MatrixListBuilder, NodeBuilder, ValueBuilder
3. Error Fixtures: 15 invalid HEDL samples, 15 invalid expressions, 8 semantically invalid documents
4. Edge Case Generators: deeply_nested_document, wide_document, long_string_document, many_references_document
5. Counting Utilities: count_nodes, count_references
6. Expression Helpers: expr, try_expr, expr_value, try_expr_value with ExprError type

Installation

[dev-dependencies]
hedl-test = { workspace = true }

Or specify version directly:

[dev-dependencies]
hedl-test = "1.2"

Pre-Built Fixtures

Basic Fixtures

use hedl_test::fixtures;

// Scalar types (all primitives)
let doc = fixtures::scalars();
// Contains: int, float, bool, null, string examples

// Special strings (escapes, Unicode, etc.)
let doc = fixtures::special_strings();
// Contains: quotes, escapes, newlines, Unicode

// References (qualified and local)
let doc = fixtures::references();
// Contains: local references (@id) and typed references (@Type:id)

// Tensors (matrix literals)
let doc = fixtures::tensors();
// Contains: 1D, 2D, 3D tensors and empty tensor

Complex Fixtures

use hedl_test::fixtures;

// User list (simple matrix)
let doc = fixtures::user_list();
// 3 users: alice, bob, charlie with id, name, email

// Mixed type list
let doc = fixtures::mixed_type_list();
// Items with int, float, bool, null, and string fields

// With references
let doc = fixtures::with_references();
// Users and Posts with author references

// With NEST hierarchy
let doc = fixtures::with_nest();
// Users with nested posts (parent-child via NEST)

// Deep NEST hierarchy
let doc = fixtures::deep_nest();
// Organization → Department → Employee (3 levels)

// Blog (nested structure)
let doc = fixtures::blog();
// Complex blog platform: users, categories, tags, posts, comments, reactions, post_tags, followers

Comprehensive Fixture

All HEDL features in one document:

use hedl_test::fixtures;

let doc = fixtures::comprehensive();
// Contains:
// - Scalar values (bool, string, int, float)
// - Expressions (function calls, identifiers, literals)
// - Tensors
// - Users list with nested posts (via NEST)
// - Comments and Tags lists
// - References between entities
// - Multiple STRUCT definitions
// - NEST directive

Builder Types

DocumentBuilder

Programmatically construct documents:

use hedl_test::fixtures::builders::DocumentBuilder;
use hedl_core::Value;

let doc = DocumentBuilder::new()
    .version(1, 0)
    .struct_def("User", vec!["id".to_string(), "name".to_string(), "email".to_string()])
    .alias("api_url", "https://api.example.com")
    .nest("User", "Post")
    .scalar("app_name", Value::String("MyApp".to_string().into()))
    .scalar("debug", Value::Bool(true))
    .build();

Methods:

• version(major, minor) - Set document version
• struct_def(name, fields) - Add struct definition
• alias(alias, target) - Add alias
• nest(parent, child) - Add NEST relationship
• scalar(name, value) - Add scalar value to root
• list(name, list) - Add MatrixList to root
• item(name, item) - Add Item to root
• build() - Build the Document

MatrixListBuilder

Build typed entity lists:

use hedl_test::fixtures::builders::MatrixListBuilder;
use hedl_core::{Node, Value};

let list = MatrixListBuilder::new("User")
    .schema(vec!["id".to_string(), "name".to_string(), "age".to_string()])
    .row(Node::new("User", "alice", vec![
        Value::String("alice".to_string().into()),
        Value::String("Alice Smith".to_string().into()),
        Value::Int(30),
    ]))
    .row(Node::new("User", "bob", vec![
        Value::String("bob".to_string().into()),
        Value::String("Bob Jones".to_string().into()),
        Value::Int(25),
    ]))
    .build();

Methods:

• schema(fields) - Set schema (all field names)
• field(field) - Add single field to schema
• row(node) - Add a row (node)
• rows(nodes) - Add multiple rows
• count_hint(count) - Set count hint
• build() - Build the MatrixList

NodeBuilder

Build individual entities:

use hedl_test::fixtures::builders::NodeBuilder;
use hedl_core::Value;

let node = NodeBuilder::new("User", "alice")
    .field(Value::String("alice".to_string().into()))
    .field(Value::String("Alice Smith".to_string().into()))
    .field(Value::Int(30))
    .build();

Methods:

• field(value) - Add a field value
• fields(values) - Add multiple field values
• children(rel_name, nodes) - Add child nodes under a relationship
• child(rel_name, node) - Add single child node
• child_count(count) - Set child count hint
• build() - Build the Node

ValueBuilder

Static helper methods for creating values:

use hedl_test::fixtures::builders::ValueBuilder;

// Scalar values
let v = ValueBuilder::null();
let v = ValueBuilder::bool_val(true);
let v = ValueBuilder::int(42);
let v = ValueBuilder::float(3.14);
let v = ValueBuilder::string("Hello");

// References
let v = ValueBuilder::reference("User", "alice");  // Qualified reference
let v = ValueBuilder::local_ref("some_id");        // Local reference

// Tensors
let v = ValueBuilder::tensor_1d(vec![1.0, 2.0, 3.0]);
let v = ValueBuilder::tensor_2d(vec![vec![1.0, 2.0], vec![3.0, 4.0]]);

Methods:

• null() - Create null value
• bool_val(value) - Create boolean value
• int(value) - Create integer value
• float(value) - Create float value
• string(value) - Create string value
• reference(type_name, id) - Create qualified reference
• local_ref(id) - Create local reference
• tensor_1d(values) - Create 1D tensor
• tensor_2d(rows) - Create 2D tensor

Error Fixtures

Invalid HEDL Syntax

use hedl_test::fixtures::errors;

// Get all invalid HEDL samples as (name, hedl_text) pairs
let samples = errors::invalid_hedl_samples();
for (name, hedl_text) in samples {
    // Test parser with invalid input
    // Each should fail to parse
}

Available samples (15 total):

• empty - Empty document
• whitespace_only - Only whitespace
• invalid_directive - Invalid directive name
• missing_separator - Missing --- separator
• invalid_version - Invalid version number
• malformed_struct - Malformed STRUCT directive
• unclosed_string - Unclosed string literal
• invalid_escape - Invalid escape sequence
• malformed_reference - Malformed reference
• invalid_tensor - Malformed tensor syntax
• mismatched_brackets - Mismatched brackets
• invalid_number - Invalid number format
• malformed_expression - Malformed expression
• invalid_identifier - Invalid identifier
• duplicate_directive - Duplicate directive

Invalid Expressions

use hedl_test::fixtures::errors;

// Get all invalid expression samples as (description, expr_string) pairs
let samples = errors::invalid_expression_samples();
for (desc, expr_str) in samples {
    // Test expression parser with invalid input
    // Each should fail to parse
}

Available samples (15 total):

• empty - Empty expression
• whitespace_only - Only whitespace
• unclosed_paren - Unclosed parenthesis
• unclosed_string - Unclosed string literal
• invalid_chars - Invalid characters
• double_dot - Double dot in path
• trailing_dot - Trailing dot
• leading_dot - Leading dot
• mismatched_parens - Mismatched parentheses
• empty_call - Empty function call
• invalid_identifier - Invalid identifier
• special_chars_only - Only special characters
• nested_unclosed - Nested unclosed parentheses
• comma_without_args - Comma without arguments
• trailing_comma - Trailing comma

Semantic Errors

Valid syntax but semantic violations:

use hedl_test::fixtures::errors;

// Get all semantically invalid documents as (name, document) pairs
let docs = errors::semantically_invalid_docs();
for (name, doc) in docs {
    // Test validation logic with semantically invalid documents
    // Each should fail validation but parse correctly
}

Available documents (8 total):

• undefined_struct - MatrixList references undefined struct
• undefined_nest - NEST directive references non-existent child type
• circular_nest - Circular NEST references (TypeA → TypeB → TypeA)
• dangling_reference - Reference points to non-existent node
• mismatched_schema - MatrixList schema doesn't match struct definition
• empty_type_name - MatrixList has empty type name
• duplicate_ids - Multiple nodes with same ID in a list
• invalid_alias - Alias references non-existent item

Edge Case Generators

Deeply Nested Document

Test parser depth limits:

use hedl_test::fixtures::errors;

let doc = errors::deeply_nested_document(1000);
// Creates 1000 levels of nested children via NEST

Use Case: Verify recursion depth limits and stack safety

Wide Document

Test handling of many entities:

use hedl_test::fixtures::errors;

let doc = errors::wide_document(1000);
// Creates a MatrixList with 1000 rows

Use Case: Verify large list handling and memory efficiency

Long Strings

Test string length limits:

use hedl_test::fixtures::errors;

let doc = errors::long_string_document(1024 * 1024);
// Creates a document with a 1 MB string value

Use Case: Verify string buffer limits and allocation safety

Many References

Test reference resolution performance:

use hedl_test::fixtures::errors;

let doc = errors::many_references_document(10_000);
// Creates 10K target nodes and 10K references

Use Case: Verify reference resolution performance and correctness

Test Utilities

Counting Utilities

use hedl_test::{count_nodes, count_references};

// Count total nodes (entities) in document
let count = count_nodes(&doc);

// Count total references in document
let ref_count = count_references(&doc);

Available functions:

• count_nodes(&doc) - Count all nodes in the document (including nested children)
• count_references(&doc) - Count all reference values in the document

Expression Utilities

use hedl_test::{expr, try_expr, expr_value, try_expr_value, ExprError};

// Create Expression from string (panics on error)
let e = expr("42");
let e = expr("now()");
let e = expr("user.name");

// Create Expression safely (returns Result)
let result = try_expr("invalid!!!");
match result {
    Ok(e) => println!("Parsed: {:?}", e),
    Err(ExprError::ParseFailed { source, input }) => {
        println!("Failed to parse '{}': {}", input, source);
    }
    Err(ExprError::EmptyInput) => println!("Empty input"),
    Err(ExprError::Missing) => println!("Missing expression"),
}

// Create Value::Expression from string
let v = expr_value("42");        // Panics on error
let v = try_expr_value("42")?;   // Returns Result

Available functions:

• expr(s) - Parse expression string, panic on error
• try_expr(s) - Parse expression string, return Result
• expr_value(s) - Create Value::Expression, panic on error
• try_expr_value(s) - Create Value::Expression, return Result

Error type:

• ExprError::EmptyInput - Expression string is empty
• ExprError::ParseFailed { source, input } - Parse failed with lexical error
• ExprError::Missing - Expression is missing or null

Quick Builder Helpers

The fixtures::builders::quick module provides convenient helper functions for common patterns:

use hedl_test::fixtures::builders::quick;

// Create document with simple scalar fields
let doc = quick::simple_scalars(vec![
    ("name", "Alice"),
    ("city", "NYC"),
]);

// Create document with simple user list
let doc = quick::simple_user_list(vec![
    ("alice", "Alice Smith", "alice@example.com"),
    ("bob", "Bob Jones", "bob@example.com"),
]);

// Create document with references
let doc = quick::with_references(
    vec![("alice", "Alice"), ("bob", "Bob")],  // users
    vec![("post1", "Title", "alice")],          // posts with author refs
);

Usage Patterns

Testing Parsers

use hedl_test::fixtures;

#[test]
fn test_parse_user_list() {
    let doc = fixtures::user_list();
    assert_eq!(doc.version, (1, 0));

    if let Some(hedl_core::Item::List(list)) = doc.root.get("users") {
        assert_eq!(list.rows.len(), 3);
        assert_eq!(list.type_name, "User");
    }
}

Testing Format Converters

use hedl_test::fixtures;

#[test]
fn test_all_fixtures() {
    for (name, fixture_fn) in fixtures::all() {
        let doc = fixture_fn();

        // Test your converter with each fixture
        let json = to_json(&doc).unwrap();
        let back = from_json(&json).unwrap();

        // Verify roundtrip
        assert_eq!(doc, back, "Fixture {} failed roundtrip", name);
    }
}

Testing Error Handling

use hedl_test::fixtures::errors;

#[test]
fn test_invalid_hedl_samples() {
    for (name, hedl_text) in errors::invalid_hedl_samples() {
        let result = parse(hedl_text);
        assert!(result.is_err(), "Sample {} should fail to parse", name);
    }
}

#[test]
fn test_semantic_errors() {
    for (name, doc) in errors::semantically_invalid_docs() {
        let result = validate(&doc);
        assert!(result.is_err(), "Document {} should fail validation", name);
    }
}

Testing Edge Cases

use hedl_test::fixtures::errors;
use hedl_test::count_nodes;

#[test]
fn test_deeply_nested() {
    let doc = errors::deeply_nested_document(100);
    let count = count_nodes(&doc);

    // Verify deep nesting is handled correctly
    assert!(count > 0);
}

#[test]
fn test_many_references() {
    let doc = errors::many_references_document(1000);

    // Test reference resolution performance
    let result = resolve_references(&doc);
    assert!(result.is_ok());
}

What This Crate Doesn't Do

Property-Based Testing: Fixtures are hand-crafted examples. For property-based testing, use proptest or quickcheck with custom generators.

Performance Testing: Fixtures designed for correctness testing. For performance, use hedl-bench with realistic workloads.

Fuzz Testing: No fuzzing infrastructure. For fuzz testing, use cargo-fuzz with custom fuzz targets.

Test Data Generation: Fixtures are static. For dynamic test data, write custom generators using builders.

Dependencies

• hedl-core - Core HEDL types and parsing
• hedl-c14n - Canonicalization for HEDL documents
• smallvec - Optimized small vector implementation

License

Apache-2.0