Fix a few bugs

Author: habedi

Makefile

@@ -6,7 +6,7 @@ BUILD_TYPE    ?= Debug
 BUILD_OPTS    ?= -Doptimize=$(BUILD_TYPE)
 JOBS          ?= $(shell nproc || echo 2)
 
-# Helper macro to ensure the Zig compiler exists
+# Helper macro to guarantee the Zig compiler exists
 check_zig = \
     if [ ! -x "$(ZIG)" ]; then \
       echo "ERROR: Zig compiler not found at '$(ZIG)'."; \

README.md

@@ -38,21 +38,21 @@ following steps:
 2. Finding cases where the input causes the property to fail.
 3. Finding smaller subsets of the failing input that still cause the failure (this is called "shrinking").
 
-For example, consider the property of a `reverse(s: string)` function that states that reversing a string twice should
-return the original string.
+For example, consider the property of a `reverse(s: []const u8)` function that states that reversing
+a string twice should return the original string.
 In property-based testing, you would define this property and let the framework generate a lot of random strings to
 test it.
 If it finds a string that makes the property fail (due to a bug in the reverse function, for example), it will then try
 to shrink that string to a simpler or shorter case that still makes the property fail.
 
 Here is a brief comparison between example-based testing and property-based testing paradigms:
 
-| Aspect        | Example-based Testing          | Property-based Testing                     |
-|---------------|--------------------------------|--------------------------------------------|
-| **Input**     | Hand-written specific values   | Auto-generated random values               |
-| **Coverage**  | Only cases you can think of    | Discovers edge cases automatically         |
-| **Debugging** | Exact failing inputs are known | Shrinks to minimal failing case            |
-| **Effort**    | Write a lot of test cases      | Define one property, test with many inputs |
+| Criterion | Example-based Testing          | Property-based Testing                     |
+|-----------|--------------------------------|--------------------------------------------|
+| Input     | Hand-written specific values   | Auto-generated random values               |
+| Coverage  | Only cases you can think of    | Discovers edge cases automatically         |
+| Debugging | Exact failing inputs are known | Shrinks to minimal failing case            |
+| Effort    | Write a lot of test cases      | Define one property, test with many inputs |
 
 ### Why Minish?
 
@@ -63,7 +63,7 @@ Here is a brief comparison between example-based testing and property-based test
 - Supports reproducible failures and verbose mode
 - Configurable and easy to integrate into existing Zig projects
 
-See the [ROADMAP.md](ROADMAP.md) for the list of implemented and planned features.
+See [ROADMAP.md](ROADMAP.md) for the list of implemented and planned features.
 
 > [!IMPORTANT]
 > Minish is in early development, so bugs and breaking changes are expected.

examples/e5_struct_and_combinators.zig

@@ -22,7 +22,7 @@ fn adult_flag_is_consistent(person: Person) !void {
 
 // Property: height should be reasonable for the age
 fn height_is_reasonable(person: Person) !void {
-    // Very basic check - just ensure height isn't absurdly large or small
+    // Very basic check - just make sure height isn't absurdly large or small
     try std.testing.expect(person.height_cm >= 30); // Even babies are >30cm
     try std.testing.expect(person.height_cm <= 250); // Very tall but possible
 }

examples/e7_hashmap_example.zig

@@ -4,7 +4,7 @@ const gen = minish.gen;
 
 // Property: getting a value we just put should return that value
 fn put_then_get_returns_value(map: std.AutoHashMap(i32, i32)) !void {
-    var mut_map = map;
+    var mut_map = try map.clone();
     defer mut_map.deinit();
 
     // Try putting and getting a known value
@@ -22,10 +22,8 @@ fn put_then_get_returns_value(map: std.AutoHashMap(i32, i32)) !void {
 
 // Property: map size should match number of unique keys inserted
 fn map_count_matches_entries(map: std.AutoHashMap(i32, bool)) !void {
-    var mut_map = map;
-    defer mut_map.deinit();
-
-    const count = mut_map.count();
+    // Treat as read-only, Minish will free it.
+    const count = map.count();
 
     // Count should be reasonable (not negative, not absurd)
     try std.testing.expect(count >= 0);
@@ -34,7 +32,7 @@ fn map_count_matches_entries(map: std.AutoHashMap(i32, bool)) !void {
 
 // Property: removing a key that doesn't exist returns false
 fn remove_nonexistent_key(map: std.AutoHashMap(i32, i32)) !void {
-    var mut_map = map;
+    var mut_map = try map.clone();
     defer mut_map.deinit();
 
     // Try to remove a key that's very unlikely to exist

examples/e8_misc_features.zig

@@ -0,0 +1,98 @@
+const std = @import("std");
+const minish = @import("minish");
+const gen = minish.gen;
+const combinators = minish.combinators;
+
+// ============================================================================
+// Misc Features Example
+// ============================================================================
+// This example showcases features not covered in other examples:
+// 1. oneOf (Choice generator)
+// 2. dependent (Monadic-like sequencing)
+// 3. timestamps
+// 4. enums
+
+// 1. oneOf: Generate values from mixed sources
+fn test_mixed_integers(val: i32) !void {
+    // We expect either small ints (0-10) or a specific large constant (1000)
+    const is_small = (val >= 0 and val <= 10);
+    const is_large = (val == 1000);
+    try std.testing.expect(is_small or is_large);
+}
+
+// 2. dependent: Generate a boolean, then use it to select a generator
+// Dependent generator creates a struct { T, U }
+fn test_dependent_logic(pair: struct { bool, i32 }) !void {
+    const is_pos = pair[0];
+    const val = pair[1];
+
+    if (is_pos) {
+        try std.testing.expect(val > 0);
+    } else {
+        try std.testing.expect(val < 0);
+    }
+}
+
+// 3. Timestamp generator
+fn test_timestamp_range(ts: i64) !void {
+    // Check it's within our requested 1-hour window
+    // 1672531200 = 2023-01-01 00:00:00 UTC
+    // 1672534800 = 2023-01-01 01:00:00 UTC
+    try std.testing.expect(ts >= 1672531200);
+    try std.testing.expect(ts <= 1672534800);
+}
+
+// 4. Enum generator
+const Color = enum { Red, Green, Blue };
+fn test_enum_colors(c: Color) !void {
+    switch (c) {
+        .Red, .Green, .Blue => {}, // All valid
+    }
+}
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    std.debug.print("\n=== Misc Features Example ===\n\n", .{});
+
+    // 1. oneOf
+    std.debug.print("Test 1: oneOf (mixed ranges)\n", .{});
+    const mixed_gen = gen.oneOf(i32, &.{
+        gen.intRange(i32, 0, 10),
+        gen.constant(@as(i32, 1000)),
+    });
+    try minish.check(allocator, mixed_gen, test_mixed_integers, .{ .num_runs = 50 });
+
+    // 2. dependent
+    // Note: dependent is limited to branching/selection logic for runtime values,
+    // as Minish generators cannot easily capture runtime state in closures.
+    std.debug.print("\nTest 2: dependent (bool -> branching logic)\n", .{});
+    const Dep = struct {
+        const bool_gen = gen.boolean();
+        const make_int_gen = struct {
+            fn make(b: bool) gen.Generator(i32) {
+                if (b) {
+                    return gen.intRange(i32, 1, 100);
+                } else {
+                    return gen.intRange(i32, -100, -1);
+                }
+            }
+        }.make;
+        const dep_gen = gen.dependent(bool, i32, bool_gen, make_int_gen);
+    };
+    try minish.check(allocator, Dep.dep_gen, test_dependent_logic, .{ .num_runs = 50 });
+
+    // 3. Timestamps
+    std.debug.print("\nTest 3: Timestamp (1 hour range)\n", .{});
+    const ts_gen = gen.timestampRange(1672531200, 1672534800);
+    try minish.check(allocator, ts_gen, test_timestamp_range, .{ .num_runs = 50 });
+
+    // 4. Enums
+    std.debug.print("\nTest 4: Enums\n", .{});
+    const enum_gen = gen.enumValue(Color);
+    try minish.check(allocator, enum_gen, test_enum_colors, .{ .num_runs = 50 });
+
+    std.debug.print("\nAll misc feature tests passed!\n", .{});
+}

src/lib.zig

@@ -2,6 +2,9 @@
 //!
 //! A property-based testing framework for Zig, inspired by [QuickCheck](https://hackage.haskell.org/package/QuickCheck) and [Hypothesis](https://hypothesis.readthedocs.io/en/latest/).
 //!
+//! Minish automatically generates random test cases and, on failure, minimises (shrinks)
+//! the input to the smallest value that still reproduces the failure. This makes debugging
+//! property violations a lot easier.
 //! ## Quick Start
 //!
 //! ```zig
@@ -43,6 +46,9 @@ pub const combinators = @import("minish/combinators.zig");
 /// Internal test case state. Used by generators to make random choices.
 pub const TestCase = @import("minish/core.zig").TestCase;
 
+/// Errors that can occur during generation.
+pub const GenError = @import("minish/core.zig").GenError;
+
 /// Run property-based tests with the given generator and property function.
 pub const check = @import("minish/runner.zig").check;
 

src/minish/combinators.zig

@@ -18,6 +18,12 @@ const Generator = gen.Generator;
 // ============================================================================
 
 /// Transform the output of a generator using a mapping function.
+///
+/// Example:
+/// ```zig
+/// // Convert generated integers to strings
+/// const string_gen = combinators.map(i32, []const u8, gen.int(i32), intToString);
+/// ```
 pub fn map(
     comptime T: type,
     comptime U: type,
@@ -38,6 +44,12 @@ pub fn map(
 // ============================================================================
 
 /// Chain generators - use the output of one generator to create another.
+///
+/// Example:
+/// ```zig
+/// // Generate a length, then a list of that length
+/// const list_gen = combinators.flatMap(usize, []const u8, gen.intRange(usize, 1, 10), makeListGen);
+/// ```
 pub fn flatMap(
     comptime T: type,
     comptime U: type,
@@ -60,6 +72,14 @@ pub fn flatMap(
 
 /// Generate values that satisfy a predicate.
 /// WARNING: This can loop indefinitely if the predicate is rarely satisfied.
+///
+/// Example:
+/// ```zig
+/// const even_gen = combinators.filter(i32, gen.int(i32), isEven, 100);
+/// ```
+///
+/// Memory lifecycle: Generated values that fail the predicate are automatically freed if associated generator has a freeFn.
+/// The retained value is owned by the Minish runner.
 pub fn filter(
     comptime T: type,
     comptime base_gen: Generator(T),
@@ -74,11 +94,21 @@ pub fn filter(
                 if (predicate(value)) {
                     return value;
                 }
+                // Free rejected value if generator provides freeFn
+                if (base_gen.freeFn) |freeFn| {
+                    freeFn(tc.allocator, value);
+                }
             }
             return error.Overrun;
         }
+
+        fn free(allocator: std.mem.Allocator, value: T) void {
+            if (base_gen.freeFn) |freeFn| {
+                freeFn(allocator, value);
+            }
+        }
     };
-    return .{ .generateFn = FilterGenerator.generate, .shrinkFn = null, .freeFn = null };
+    return .{ .generateFn = FilterGenerator.generate, .shrinkFn = null, .freeFn = FilterGenerator.free };
 }
 
 // ============================================================================
@@ -101,6 +131,18 @@ pub fn sized(
 // ============================================================================
 
 /// Choose from generators with weighted probabilities.
+///
+/// Example:
+/// ```zig
+/// // 90% chance of 0, 10% chance of random int
+/// const biased_gen = combinators.frequency(i32, &.{
+///     .{ .weight = 90, .gen = gen.constant(@as(i32, 0)) },
+///     .{ .weight = 10, .gen = gen.int(i32) }
+/// });
+/// ```
+///
+/// Memory lifecycle: The returned value is owned by the Minish runner and will be freed automatically.
+/// Assumes all weighted generators share compatible memory management.
 pub fn frequency(
     comptime T: type,
     comptime weighted_gens: []const struct { weight: u64, gen: Generator(T) },
@@ -118,9 +160,62 @@ pub fn frequency(
             const idx = try tc.weightedChoice(&weights);
             return weighted_gens[idx].gen.generateFn(tc);
         }
+
+        fn free(allocator: std.mem.Allocator, value: T) void {
+            // Assume homogeneity: use first generator's freeFn if available
+            if (weighted_gens.len > 0 and weighted_gens[0].gen.freeFn != null) {
+                weighted_gens[0].gen.freeFn.?(allocator, value);
+            }
+        }
     };
-    return .{ .generateFn = FrequencyGenerator.generate, .shrinkFn = null, .freeFn = null };
+    return .{ .generateFn = FrequencyGenerator.generate, .shrinkFn = null, .freeFn = FrequencyGenerator.free };
 }
 
 // Note: Combinator tests are demonstrated in examples/e5_struct_and_combinators.zig
 // They cannot be easily unit tested due to comptime parameter requirements
+
+test "combinator memory leak regression tests" {
+    const runner = @import("runner.zig");
+    const allocator = std.testing.allocator;
+    const str_gen = comptime gen.string(.{ .min_len = 1, .max_len = 5 });
+
+    const opts = runner.Options{ .seed = 111, .num_runs = 10 };
+
+    const Props = struct {
+        fn prop_no_op(_: []const u8) !void {}
+    };
+
+    // Test Frequency
+    const freq_gen = frequency([]const u8, &.{
+        .{ .weight = 10, .gen = str_gen },
+        .{ .weight = 10, .gen = str_gen },
+    });
+    try runner.check(allocator, freq_gen, Props.prop_no_op, opts);
+}
+
+test "filter memory leak regression test" {
+    const runner = @import("runner.zig");
+    const allocator = std.testing.allocator;
+
+    // Generate strings, keep only those starting with 'A'.
+    // Rejected strings (allocations) should be freed by filter.
+    const str_gen = comptime gen.string(.{ .min_len = 1, .max_len = 5, .charset = .alphanumeric });
+
+    const startsWithA = struct {
+        fn func(s: []const u8) bool {
+            if (s.len == 0) return false;
+            return s[0] == 'A';
+        }
+    }.func;
+
+    // We filter, max 1000 attempts to allow many rejections without failure.
+    const filtered_gen = filter([]const u8, str_gen, startsWithA, 1000);
+
+    const opts = runner.Options{ .seed = 111, .num_runs = 10 };
+
+    const Props = struct {
+        fn prop_no_op(_: []const u8) !void {}
+    };
+
+    try runner.check(allocator, filtered_gen, Props.prop_no_op, opts);
+}

src/minish/core.zig

@@ -20,7 +20,12 @@ pub const GenError = error{
 };
 
 /// TestCase manages the state for a single property test run.
-/// It tracks random choices made during generation to enable shrinking.
+///
+/// Responsibilities:
+/// - **Randomness**: Provides the source of random choices for generators.
+/// - **Recording**: Records every choice made during generation. This trace is used
+///   reproduce failures or to guide shrinking (by modifying the trace).
+/// - **Shrinking**: When replaying for shrinking, can force specific choices.
 pub const TestCase = struct {
     allocator: Allocator,
     prng: DefaultPrng,