regorus/tests/rvm/vm/README.md

Regorus VM Test Suites

This directory hosts YAML-driven regression suites for the Regorus virtual machine. Each YAML file is converted into parameterised Rust tests by src/rvm/tests/vm.rs, so the contents here define the end-to-end VM coverage.

Prerequisites

• Enable the rvm feature (it pulls in std and the VM runtime) whenever you run these tests:
  • cargo test --features rvm run_vm_test_file
  • cargo test --features rvm run_loop_test_file
• Append -- --nocapture to surface per-test diagnostics when a failure occurs.
• Individual generated tests follow the pattern run_vm_test_file_tests_rvm_vm_suites_<suite>_yaml, so you can use that fragment with cargo test to run a single suite.

Layout

• suites/*.yaml — primary instruction, control-flow, and integration suites.
• suites/loops/*.yaml — dedicated loop/comprehension suites.
• Mirror the comment headers inside each suite when adding new files; the descriptions are surfaced in this README for quick reference.

Main Suites (suites/*.yaml)

Suite	Focus
arithmetic_operations.yaml	Arithmetic opcodes (Add, Sub, Mul, Div, Mod) and simple expressions.
assertions.yaml	AssertCondition semantics, including success/failure and loop control interactions.
basic_instructions.yaml	Core load/move/return instructions that underpin every program.
boolean_literals.yaml	LoadBool, LoadTrue, LoadFalse, and their interaction with logical operators.
builtin_functions.yaml	Builtin dispatch covering argument marshalling, return handling, and error cases.
call_rule.yaml	CallRule execution, rule caches, defaults, and fallbacks.
comparison_operations.yaml	Relational operators plus logical combining (Eq, Ne, Lt, Le, Gt, Ge, And, Or, Not).
complex.yaml	Deeply nested hybrid loops, comprehensions, and rule calls that stress the scheduler.
constructed_collections.yaml	ArrayCreate/SetCreate success paths, undefined propagation, and deduplication.
control_flow.yaml	Conditional branching patterns, nested assertions, and selection logic.
core_semantics.yaml	Broad regression coverage for arithmetic, comparisons, loops, assertions, and collection helpers.
data_structures.yaml	Array/object/set creation, access, and mutation instructions.
deep_nesting.yaml	Three-plus levels of mixed loop modes validating register pressure and control flow correctness.
default_rules.yaml	Complete rule execution with default literals and failure fallbacks.
destructuring_rules.yaml	Destructuring metadata handling, success/early-exit semantics.
function_calls.yaml	User function invocation plumbing, argument passing, and returns.
halt.yaml	Halt instruction returning register 0 and stopping execution.
host_await.yaml	Successful HostAwait responses across execution modes and run-to-completion flows.
host_await_failures.yaml	Error signalling and ignore-flag behaviour for HostAwait.
indexed_access.yaml	Literal/register indexing, chained accesses, and undefined propagation.
integration_scenarios.yaml	Real-world policy shapes (RBAC, filtering, transforms, workflows).
interpreter_operator_compatibility.yaml	Ensures VM operators match interpreter behaviour on edge cases.
invalid_collection_ops.yaml	Error paths for object/set/array mutations with incorrect types.
load_data_input.yaml	LoadData and LoadInput instructions across nested/empty/undefined sources.
loop_invalid_iteration.yaml	Loop errors for non-iterables plus instruction-limit enforcement.
null_undefined_handling.yaml	Null/undefined behaviour across arithmetic, comparisons, indexing, loops, and comprehensions.
object_operations.yaml	Advanced object templates, dynamic keys, collisions, and validation.
predefined.yaml	Global data and input bindings, including nested access patterns.
resource_limits.yaml	Instruction counts, recursion depth, and other resource exhaustion scenarios.
serialization.yaml	Round-trip binary serialization for compiled programs covering all instruction families.
set_operations.yaml	Set creation, deduplication, membership checks, and nested values.
type_errors.yaml	Graceful error reporting for cross-family type mismatches.
virtual_data_lookup.yaml	VirtualDataDocumentLookup with base data, rule overrides, and invalid indices.

Loop Suites (suites/loops/*.yaml)

Suite	Focus
array_comprehensions.yaml	Mapping, filtering, and edge cases for array comprehensions.
empty.yaml	Behaviour of every loop mode over empty collections (vacuous truth/falsehood).
existential.yaml	some-style (Any) quantification including early exits and complex predicates.
loop_comprehension_interactions.yaml	Interplay between nested loops and comprehensions emitting structured data.
nested.yaml	Mixed nesting patterns for loops and comprehensions with varying depth.
nested_fixed.yaml	Placeholder for future fixed-nesting scenarios (no cases yet).
object_comprehensions.yaml	Key/value emission, collision handling, and filtering in object comprehensions.
set_comprehensions.yaml	Deduplication and uniqueness guarantees in set comprehensions.
universal.yaml	every-style (Every) quantification, early failure, and vacuous truth cases.

Adding or Updating Suites

1. Place the new YAML file under suites/ (or the relevant suites/loops/ subdirectory).
2. Add a concise comment block at the top describing the intent and scenarios.
3. Update the tables above so the catalog stays accurate.
4. Run cargo test --features rvm run_vm_test_file to ensure the suite loads and all cases pass.

Keeping this README current makes it easier to discover coverage gaps and reason about the generated tests.