Enhance flux-testkit: rich assertions, builder, fixtures, property-based testing, snapshots

README.md

@@ -1,25 +1,48 @@
-# FLUX TestKit — Test Harness Framework
+# FLUX TestKit — Comprehensive Test Harness for FLUX VM Programs
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-Write and run FLUX program tests with assertion helpers.
+Write and run FLUX program tests with rich assertion helpers, fixture generators, and property-based testing.
 
 ## Features
-- Test suite definition with `add_test()` or `@test` decorator
-- Assertion helpers: `assert_register`, `assert_cycles`, `assert_bytecode_size`, `assert_true`
-- Built-in lightweight VM for test execution
-- Markdown report generation with ✅/❌/💥 icons
-- Error handling with graceful failure reporting
+
+- **Assertion helpers**: `assert_register_eq`, `assert_register_ne`, `assert_register_range`, `assert_flag_zero`, `assert_flag_negative`, `assert_halted`, `assert_true`, `assert_false`, `assert_greater`, `assert_less`, `assert_in_range`, `assert_cycles`, `assert_bytecode_size`, `assert_no_error`, `skip`
+- **BytecodeBuilder**: Fluent builder for constructing FLUX bytecode programs (movi, add, sub, mul, div, mod, and_, or_, xor, seq, slt, movr, beq, bne, incr, decr, push, pop, nop, halt)
+- **Fixture generators**: Pre-built test programs (movi, add, factorial, loop, NOP sled, push/pop, edge cases), plus seeded random generators
+- **Property-based testing**: `PropertyChecker` with `for_all_values` and `for_all_bytecodes` for fuzz-like testing with counterexample reporting
+- **Snapshot testing**: `SnapshotTester` for disassembly output comparison (auto-create, match, mismatch detection, update mode)
+- **Per-opcode reporting**: Tag tests with opcode names and get pass/fail rates per opcode
+- **Multi-format reports**: Terminal, Markdown, and JSON
+- **Disassembler**: Human-readable disassembly of FLUX bytecode
 
 ## Usage
+
 ```python
-from testkit import FluxTestSuite
+from testkit import FluxTestSuite, FluxTestContext, BytecodeBuilder, FixtureGenerator, PropertyChecker, SnapshotTester, disassemble
 
+# Basic suite
 suite = FluxTestSuite("my_tests")
-suite.add_test("factorial", lambda ctx, vm: (
-    ctx.assert_register(vm.run([0x18,0,6, 0x18,1,1, 0x22,1,1,0, 0x09,0, 0x3D,0,0xFA,0, 0x00])[0], 1, 720)
+suite.add_test("add", lambda ctx, vm: ctx.assert_register(
+    vm.run([0x18,0,10, 0x18,1,20, 0x20,2,0,1, 0x00])[0], 2, 30
 ))
 result = suite.run()
 print(result.to_markdown())
+print(result.per_opcode_report())
+
+# BytecodeBuilder
+bc = BytecodeBuilder().movi(0, 10).movi(1, 20).add(2, 0, 1).halt().build()
+
+# Fixtures
+bc = FixtureGenerator.factorial_program(6)
+
+# Property-based testing
+checker = PropertyChecker(seed=42)
+result = checker.for_all_values("positive", range(1, 1000), lambda x: x > 0)
+
+# Snapshot testing
+st = SnapshotTester()
+ok, msg = st.assert_match_snapshot("my_test", bc)
+
+# Disassembly
+print(disassemble(bc))
 ```
 
-8 tests passing.
+56 tests passing.