core/src/ast/tests/README.md

Evidence DSL Test Suite

Overview

This comprehensive test suite follows a structural linguistic approach to validate the Evidence DSL (Domain Specific Language) for authorization policies. The tests are organized incrementally from basic language primitives to complex integration scenarios.

Test Structure

1. Structural Linguistic Tests (StructuralLinguisticTests.js)

Level: Comprehensive

• Lexical Primitives: Identifiers, literals, keywords, whitespace
• Basic Expressions: Arithmetic, logical, comparison, temporal
• Type System: Definitions, fields, behaviors, caching
• Fact System: Declarations, properties, caching, limits
• Evidence System: Rules, defeasible logic, pattern matching
• Measure System: Aggregation, fusion, return types
• Complex Integration: Multi-feature combinations

2. Expression Tests (ExpressionTests.js)

Level: Focused

• Arithmetic operator precedence
• Logical operator precedence
• Comparison operators
• Temporal expressions
• Unary operators
• Attribute access
• Function calls
• Complex expressions
• Error handling

3. Definition Tests (DefinitionTests.js)

Level: Focused

• Basic type definitions
• Field types (string, number, boolean, timestamp, custom)
• Array types
• Behaviors (decay, blur, TTL)
• Caching (eager, lazy)
• Complex definitions
• Error handling

4. Fact Tests (FactTests.js)

Level: Focused

• Basic fact declarations
• Fact properties (transitive, symmetrical)
• Fact caching
• Fact limits
• Parameter types
• Complex facts
• Error handling

5. Evidence Tests (EvidenceTests.js)

Level: Focused

• Basic evidence rules
• Defeasible logic (ALWAYS, WHEN/UNLESS, REQUIRES)
• Pattern matching with wildcards
• Fusion strategies (min, max, majority, average)
• Complex evidence composition
• Error handling

6. Measure Tests (MeasureTests.js)

Level: Focused

• Basic measure definitions
• Return types
• Aggregation with different strategies
• Fusion with different strategies
• Complex measures
• Error handling

7. Integration Tests (IntegrationTests.js)

Level: Integration

• Complete authorization systems
• Multi-domain systems
• Hierarchical access patterns
• Similarity-based access
• Temporal access patterns
• Complex behaviors
• Performance scenarios

Test Runner (TestRunner.js)

The test runner orchestrates all test suites and provides:

• Comprehensive Testing: Run all test suites
• Selective Testing: Run specific test suites
• Level-based Testing: Run tests by complexity level
• Detailed Reporting: Summary and detailed results
• Coverage Analysis: Language feature coverage

Usage

Run All Tests

import { runAllTests } from './tests/TestRunner.js';

const results = runAllTests(arbiter);
console.log(`Tests: ${results.passed}/${results.total} passed`);

Run Specific Test Suites

import { runSpecificTests } from './tests/TestRunner.js';

const results = runSpecificTests(arbiter, [
  'Expression Tests',
  'Definition Tests'
]);

Run Tests by Level

import { runTestsByLevel } from './tests/TestRunner.js';

// Run only focused tests
const results = runTestsByLevel(arbiter, 'focused');

// Run only integration tests
const results = runTestsByLevel(arbiter, 'integration');

Language Feature Coverage

✅ Lexical Primitives

• Identifiers (simple, with underscores, with numbers)
• Literals (string, number, boolean, duration)
• Keywords (reserved words)
• Whitespace and comments

✅ Expression System

• Arithmetic operators (+, -, *, /) with precedence
• Logical operators (&&, ||, NOT) with precedence
• Comparison operators (==, !=, >, <, >=, <=)
• Temporal expressions (within)
• Unary operators (NOT, !)
• Attribute access (object.attribute)
• Function calls (predicate(args))

✅ Type System

• Type definitions with fields
• Field types (string, number, boolean, timestamp, custom)
• Array types (Type[])
• Behaviors (decay, blur, TTL)
• Caching directives (eager, lazy)

✅ Fact System

• Fact declarations with parameters
• Fact properties (transitive, symmetrical)
• Caching directives
• Limits for performance
• Parameter types

✅ Evidence System

• Basic evidence rules
• Defeasible logic (ALWAYS, WHEN/UNLESS, REQUIRES)
• Pattern matching with wildcards (*)
• Binding clauses (|variable|)
• With clauses (with condition)
• Limits for pattern matching
• Fusion strategies (min, max, majority, average)

✅ Measure System

• Measure definitions
• Return type specifications (PROVIDES)
• Aggregation with strategies (USING)
• Fusion with strategies
• Complex value computation

✅ Integration Features

• Multi-domain systems
• Hierarchical access patterns
• Similarity-based access
• Temporal access patterns
• Complex behavior combinations
• Performance optimization scenarios

Test Philosophy

Structural Linguistic Approach

The tests follow a structural linguistic methodology:

1. Phonological Level: Basic lexical elements (identifiers, literals)
2. Morphological Level: Word formation (operators, keywords)
3. Syntactic Level: Grammar rules (expressions, statements)
4. Semantic Level: Meaning (types, behaviors, logic)
5. Pragmatic Level: Usage (integration, real-world scenarios)

Incremental Complexity

Tests progress from simple to complex:

• Level 1: Lexical primitives
• Level 2: Basic expressions
• Level 3: Type system
• Level 4: Fact system
• Level 5: Evidence system
• Level 6: Measure system
• Level 7: Complex integration

Comprehensive Coverage

Each language feature is tested for:

• Valid cases: Correct syntax and semantics
• Invalid cases: Error handling and recovery
• Edge cases: Boundary conditions
• Integration: Multi-feature combinations

Running Tests

Prerequisites

• Node.js environment
• Arbiter instance for testing
• All dependencies installed

Basic Usage

# Run all tests
npm test

# Run specific test file
node src/ast/tests/StructuralLinguisticTests.js

# Run with specific arbiter
node -e "
import { runAllTests } from './src/ast/tests/TestRunner.js';
const results = runAllTests(arbiter);
console.log(results);
"

Test Output

The test runner provides:

• Progress indicators: Real-time test execution
• Detailed results: Pass/fail status for each test
• Error reporting: Specific error messages for failures
• Performance metrics: Execution time for each suite
• Coverage analysis: Language feature coverage

Contributing

When adding new tests:

1. Follow the structural linguistic approach
2. Test both valid and invalid cases
3. Include error handling tests
4. Document test purpose and expected behavior
5. Maintain incremental complexity
6. Update coverage documentation

Test Maintenance

• Regular Updates: Keep tests current with language changes
• Performance Monitoring: Track test execution time
• Coverage Analysis: Ensure comprehensive feature coverage
• Error Handling: Validate error messages and recovery
• Integration Testing: Test real-world scenarios