Hedgehog for .NET

Property-based testing allows you to describe invariants (properties) that should hold true for all possible inputs, rather than writing individual test cases with specific values. Hedgehog automatically generates hundreds of random test cases to attempt to falsify these properties.

For example, instead of testing reverse with [1, 2, 3], you define the property: reverse (reverse xs) = xs for all lists xs.

property {
    let! xs = Gen.list (Range.linear 0 100) Gen.alpha
    return List.rev (List.rev xs) = xs
}
|> Property.render

An Inverse (or Roundtrip) property verifies that an operation can be undone. If you perform an operation and then its inverse, you should return to the original state.

Common Examples:

• Serialize $\rightarrow$ Deserialize = identity
• Encode $\rightarrow$ Decode = identity
• Compress $\rightarrow$ Decompress = identity
• Add $\rightarrow$ Subtract = identity

open Hedgehog
open Hedgehog.FSharp
open System.Text.Json
open Swensen.Unquote

[<Fact>]
let ``Serialize should roundtrip when deserializing`` () =
    property {
        let! person = Gen.auto<Person>
        let json = JsonSerializer.Serialize(person)
        let restored = JsonSerializer.Deserialize<Person>(json)
        test <@ restored = person @>
    }
    |> Property.check

Property-based testing (PBT) shifts the focus from testing specific values to testing universal truths. Instead of verifying that add(1, 2) == 3, you verify that for any two integers a and b, add(a, b) == add(b, a) (commutativity).

Core Principles:

• Properties over Examples: Seek universal truths that hold for all valid inputs.
• Generative Thinking: Consider the entire space of possible inputs (empty collections, max/min values, Unicode, etc.).
• Shrinking: When a test fails, Hedgehog automatically finds the minimal failing case to simplify debugging.
• Specification by Properties: Use properties as executable documentation of how your code behaves.

When creating custom AutoGenConfig instances, always start with AutoGenConfig.empty.

Why? AutoGenConfig.defaults includes generators for all built-in types. If you use defaults and then add a custom generator at a higher layer (like a Property level), the default generator from the defaults object might override your custom one during the merge process. Starting with empty ensures you only include the generators you explicitly add, as the default layer is already applied by Hedgehog automatically.

When designing property-based tests, use these common patterns to define what your code should satisfy:

To minimize maintenance burden, ensure your properties are distinct and non-overlapping. Use the following elimination workflow:

1. Discovery: List all candidate properties.
2. Analysis: Examine relationships between them.
3. Elimination: Remove redundancy using these criteria:
   • If property A failing implies property B must also fail, keep only the stronger one.
   • If property A is a special case of B, keep B.
   • If they express the same invariant with different wording, keep the clearest one.
4. Proposal: Present the minimal set of properties.

An Oracle property compares your implementation against a known 'truth'—such as a standard library function, a mathematical formula, or a simpler (but slower) legacy implementation.

Common Examples:

• Custom sort should match List.sort.
• sqrt(x)^2 should approximately equal x.
• Custom parser should match a standard parser.

open Hedgehog
open Hedgehog.FSharp
open Swensen.Unquote

[<Fact>]
let ``Custom sort should match standard sort`` () =
    property {
        let! list = Gen.list (Range.linear 0 100) Gen.int32
        let custom = myCustomSort list
        let standard = List.sort list
        test <@ custom = standard @>
    }
    |> Property.check

An Invariant is a property that always holds about the result, regardless of the input. Use this when certain aspects of your data must be preserved by an operation.

Common Examples:

• Sorting preserves the count and contents of a list.
• Mapping over a list preserves its length.
• Filtering never increases the size of a collection.
• String trimming never increases the string length.

open Hedgehog
open Hedgehog.FSharp
open Swensen.Unquote

[<Fact>]
let ``Sort should preserve all elements`` () =
    property {
        let! list = Gen.list (Range.linear 0 100) Gen.int32
        let sorted = List.sort list
        test <@ List.length sorted = List.length list @>
        test <@ List.forall (fun x -> List.contains x sorted) list @>
    }
    |> Property.check