Technical Documentation & API Reference

Architecture & Overview #

hegeltest is a state-of-the-art property-based testing and fuzzing engine for Dart and Flutter. Unlike traditional randomized testing that sprays arbitrary values, Hegel is built upon a high-performance native Rust core (libhegel) communicating via zero-copy C-FFI.

Quickstart: Dart Core #

Add hegeltest to your Dart project's dev_dependencies:

dart pub add dev:hegeltest

Write your first property test in test/math_test.dart:

import 'package:test/test.dart';
import 'package:hegeltest/hegeltest.dart';

void main() {
  hegelTest('addition is commutative across integers', (tc) {
    final a = tc.draw(integers(), label: 'a');
    final b = tc.draw(integers(), label: 'b');
    expect(a + b, equals(b + a));
  }, testCases: 200);
}

Run standard Dart tests as usual. Hegel's Dart build hook dynamically unpacks and links the native library:

dart test

Quickstart: Flutter #

Flutter projects use flutter_test rather than package:test. Install hegeltest_flutter to seamlessly bind the property runner inside Flutter's widget testing lifecycle:

flutter pub add dev:hegeltest_flutter

Create a test in test/widget_property_test.dart:

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:hegeltest_flutter/hegeltest_flutter.dart';

void main() {
  hegelFlutterWidgetTest('text renders correctly without throwing', (tc, tester) async {
    final title = tc.draw(text(minSize: 1, maxSize: 80), label: 'title');
    await tester.pumpWidget(MaterialApp(
      home: Scaffold(body: Center(child: Text(title))),
    ));
    expect(find.text(title), findsOneWidget);
  });
}

Property Testing vs Unit Testing #

Traditional unit tests verify software by asserting hand-picked examples: "When given [1, 2, 3], return [3, 2, 1]". This leaves massive voids where edge cases hide: empty collections, Unicode zero-width spaces, integer overflows, NaN, and complex state sequences.

Property-based testing inverts this paradigm: you define universal invariants (e.g. "Reversing a list twice returns the identical list" or "Encoding then decoding JSON produces an equivalent object"), and Hegel automatically constructs hundreds of adversarial inputs to break your assertions.

Deterministic Binary Shrinking #

When random fuzzing discovers a defect, the failing input is usually bloated with dozens of irrelevant fields and noise. Hegel's native Rust engine executes deterministic byte-level shrinking:

• Input generation is driven by a canonical byte choice buffer consumed through FFI.
• Upon failure, the engine applies binary search, bit deletion, zero-byte minimization, and token reductions directly to the input choice buffer.
• The test iteration is repeatedly re-executed until the minimal reproducing counterexample is isolated.

Stateful Invariant Verification #

Stateful systems (caches, state management stores, database drivers, UI navigation stacks) fail due to subtle sequences of actions rather than a single input. With StateMachine, you declare actions and invariants:

class StackMachine extends StateMachine {
  final List<int> actual = [];
  int modelCount = 0;

  @override
  List<StateRule> get rules => [
    StateRule('push', execute: (tc) {
      final val = tc.draw(integers());
      actual.add(val);
      modelCount++;
    }),
    StateRule('pop', precondition: () => actual.isNotEmpty, execute: (tc) {
      actual.removeLast();
      modelCount--;
    }),
  ];

  @override
  List<StateInvariant> get invariants => [
    StateInvariant('actual length equals model count', check: (tc) {
      expect(actual.length, equals(modelCount));
    }),
  ];
}

void main() {
  hegelTest('stack preserves model invariant', () => StackMachine());
}

Persistent Regression Database (.hegel/) #

When Hegel discovers a failing input, it persists the minimal reproduction seed to .hegel/examples/ on disk. On every subsequent test execution:

1. Phase 1 (Reuse): Prior failures are loaded from disk and replayed on iteration 1. If your bug was not fixed, the test fails in sub-milliseconds without wasting cycles generating new random values.
2. Phase 2 (Generate): If all known historical failures pass, fresh property exploration continues.
3. Phase 3 (Shrink): If a new failure is encountered, it is minimized and saved back to the database.

Generators Cheat Sheet #

Import either package:hegeltest/hegeltest.dart or package:hegeltest/generators.dart to access the comprehensive generator catalog.

1. Primitives & Numbers

2. Strings & Text

3. Collections

4. Combinators & Weighted Sampling

5. Temporal & Network

Distribution Contracts & Coverage #

A hidden weakness in randomized testing is test distribution drift. If your generator accidentally produces empty lists 99% of the time, complex business logic for populated lists never executes.

hegeltest solves this with executable Coverage Contracts:

hegelTest('payment routing satisfies SLA distribution contracts', (tc) {
  final tier = tc.draw(
    sampledWeighted([
      (70, 'standard'),
      (25, 'pro'),
      (5, 'enterprise'),
    ]),
    label: 'tier',
  );

  final cart = tc.draw(lists(integers(min: 1, max: 500), minSize: 0, maxSize: 50));

  // 1. Classify observations for distribution quality telemetry
  tc.classify(cart.isEmpty, 'empty cart', label: 'cart_state');
  tc.classify(cart.length >= 20, 'bulk items', label: 'cart_state');

  // 2. Enforce minimum coverage contracts
  tc.cover(2.0, tier == 'enterprise', 'enterprise tier exercised');
  tc.cover(10.0, cart.isEmpty, 'empty cart edge case exercised');

  final invoice = processOrder(tier, cart);
  expect(invoice.total, greaterThanOrEqualTo(0));
}, testCases: 300);

Telemetry Output

When running tests with verbosity: Verbosity.verbose or via the standalone runner, Hegel prints the exact percentage breakdown of every classification and coverage target:

Collected distribution statistics:
  cart_state:
    68.7% normal (1-19 items)
    19.3% bulk items
    12.0% empty cart
  tier:
    70.3% standard
    24.7% pro
     5.0% enterprise [Target: >= 2.0% - PASSED]

Flutter Testing Deep Dive #

hegeltest_flutter provides five purpose-built testing harnesses targeting different levels of Flutter application architecture:

1. Accessibility Monkey Fuzzing (hegelFlutterMonkeyTest)

Traverses Flutter's active SemanticsOwner tree, discovers actionable accessibility elements (buttons, inputs, sliders, scrollables), and executes randomized interactive action sequences. When a crash occurs, Hegel shrinks the action sequence to the minimal steps to reproduce:

hegelFlutterMonkeyTest(
  'fuzzes checkout workflow without crashing',
  createWidget: (tc) => const CheckoutApp(),
  steps: 30,
  allowedActions: [
    SemanticsAction.tap,
    SemanticsAction.setText,
    SemanticsAction.scrollDown,
  ],
  invariant: (tc, tester) async {
    expect(find.byType(CheckoutApp), findsOneWidget);
  },
);

2. Layout & Screen Size Sweeps (hegelFlutterLayoutSweepTest)

Sweeps viewport constraints, device pixel ratios, right-to-left localizations, and dynamic user font scaling factors (TextScaler) to detect layout overflows (A RenderFlex overflowed by ... pixels):

hegelFlutterLayoutSweepTest(
  'user card never overflows across screen sizes and text scales',
  sweepConfig: const LayoutSweepConfig(
    minWidth: 320,
    maxWidth: 1024,
    minHeight: 480,
    maxHeight: 1200,
    minTextScale: 0.8,
    maxTextScale: 2.5,
  ),
  builder: (tc, sample) => const UserProfileCard(),
);

Performance & Benchmark Metrics #

Hegel is architected to eliminate the traditional performance bottlenecks of property-based testing in Dart. By pairing a high-throughput native Rust PRNG choice stream with zero-copy C-FFI pinned memory buffers, test suites run at production scale without stalling developer feedback loops.

Empirical Benchmark Telemetry

Measurements executed using benchmark/run_benchmarks.dart with JIT warmup cycles and statistical outlier elimination:

Running Benchmarks Locally

The benchmark runner is built into hegel-dart with zero third-party dependencies:

# Run full benchmark suite and print ASCII table:
dart run benchmark/run_benchmarks.dart

# Output GitHub-flavored Markdown for CI summaries:
dart run benchmark/run_benchmarks.dart --format=markdown

# Output structured JSON for telemetry dashboards:
dart run benchmark/run_benchmarks.dart --format=json

CI/CD Caching Recipes #

Persist the .hegel/ regression database across CI runs using GitHub Actions cache. This ensures tests fail immediately on iteration 1 if an old regression reappears:

- name: Cache Hegel counterexamples
  uses: actions/cache@v4
  with:
    path: .hegel/
    key: hegel-${{ runner.os }}-${{ github.ref_name }}
    restore-keys: |
      hegel-${{ runner.os }}-main
      hegel-${{ runner.os }}-

Configuration & Environment Flags #