falsify

https://github.com/well-typed/falsify
Admin
falsify is a Haskell library that reimagines internal shrinking for property-based testing.
Tokens:4,289
Snippets:30
Trust Score:7.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Generate Integers with Falsify Ranges in Haskell

Source: https://context7.com/well-typed/falsify/llms.txt

This code illustrates how to generate integers within specific ranges using Falsify's `Range` module. It shows examples of shrinking towards the origin using `Range.between` and `Range.withOrigin`, as well as skewed generation with `Range.skewedBy`.

```haskell
import Test.Falsify.Generator (Gen)
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range

-- Generate integer 0-100, shrinks towards 0
genNonNegative :: Gen Int
genNonNegative = Gen.inRange $ Range.between (0, 100)

-- Generate integer -100 to 100, shrinks towards 0
genSmallInt :: Gen Int
genSmallInt = Gen.inRange $ Range.withOrigin (-100, 100) 0

-- Generate with skew towards smaller values (useful for list indices)
genSkewed :: Gen Int
genSkewed = Gen.inRange $ Range.skewedBy 3 (0, 1000)

```

--------------------------------

### Choose Between Generators with Falsify Selectors in Haskell

Source: https://context7.com/well-typed/falsify/llms.txt

This snippet showcases how to use Falsify's selective functor combinators to choose between different generators while preserving independent shrinking. It includes examples of `Gen.choose` for binary choices, `Gen.oneof` for multiple choices with equal weight, and `Gen.frequency` for weighted choices.

```haskell
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range
import Data.List.NonEmpty (NonEmpty(..))

-- Choose between two generators, shrinks towards first
genEitherIntOrBool :: Gen (Either Int Bool)
genEitherIntOrBool = Gen.choose
    (Left <$> Gen.int (Range.between (0, 100)))
    (Right <$> Gen.bool False)

-- Choose from multiple generators with equal weight
genOneOfThree :: Gen Int
genOneOfThree = Gen.oneof $ 
    Gen.int (Range.between (0, 10)) :| 
    [ Gen.int (Range.between (100, 110))
    , Gen.int (Range.between (1000, 1010))
    ]

-- Frequency-weighted choice
genWeighted :: Gen Char
genWeighted = Gen.frequency
    [ (3, pure 'a')  -- 3/6 = 50% of the time
    , (2, pure 'b')  -- 2/6 = 33% of the time
    , (1, pure 'c')  -- 1/6 = 17% of the time
    ]

```

--------------------------------

### Interactive Testing in GHCi (Haskell)

Source: https://context7.com/well-typed/falsify/llms.txt

Enables interactive experimentation with generators and properties directly within the GHCi environment. Provides functions to sample generators, find and shrink counterexamples, and falsify properties, offering immediate feedback during development.

```haskell
import Test.Falsify.Interactive
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range
import qualified Test.Falsify.Predicate as P

-- Sample a generator
> sample $ Gen.int (Range.between (0, 100))
42

-- Sample a list
> sample $ Gen.list (Range.between (0, 5)) (Gen.bool False)
[True, False, True]

-- Find and shrink a counterexample
> shrink (x -> x < 50) $ Gen.int (Range.between (0, 100))
Just 50

-- Falsify a property (returns Nothing if property holds)
> falsify $ do
    x <- gen $ Gen.int (Range.between (0, 100))
    assert $ P.lt .$ ("x", x) .$ ("bound", 50)
Just "x >= bound\nx    : 50\nbound: 50"
```

--------------------------------

### Configure Test Options with TestOptions

Source: https://context7.com/well-typed/falsify/llms.txt

Customize test behavior using TestOptions, including verbose mode, shrink limits, and expected failures. This allows fine-grained control over how properties are tested.

```haskell
import Data.Default
import Test.Tasty
import Test.Tasty.Falsify

tests :: TestTree
tests = testGroup "Configured tests" [
    -- Default options (100 tests, shrinking enabled)
    testProperty "default" prop_default

    -- Verbose mode shows all generated values
  , testPropertyWith def { overrideVerbose = Just Verbose }
      "verbose" prop_verbose

    -- Limit shrinking steps
  , testPropertyWith def { overrideMaxShrinks = Just 0 }
      "no_shrinking" prop_noShrink

    -- Expect the test to fail
  , testPropertyWith def { expectFailure = ExpectFailure }
      "expected_failure" prop_shouldFail

    -- Custom number of tests
  , testPropertyWith def { overrideNumTests = Just 1000 }
      "many_tests" prop_manyTests
  ]
```

--------------------------------

### Label and Collect Test Statistics

Source: https://context7.com/well-typed/falsify/llms.txt

Track distribution of test data using `label` and `collect` to ensure good coverage. This helps in understanding the generated data and identifying potential biases.

```haskell
import Test.Tasty.Falsify
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range

prop_distribution :: Property ()
prop_distribution = do
    x <- gen $ Gen.int $ Range.between (0, 100)
    y <- gen $ Gen.int $ Range.between (0, 100)

    -- Label with boolean condition
    collect "same sign" [x * y >= 0]

    -- Multiple labels
    label "x range" [
        if x < 25 then "small"
        else if x < 75 then "medium"
        else "large"
      ]

    -- Falsify reports percentages for each label value
    return ()
```

--------------------------------

### Derive Generators Automatically with GenDefault

Source: https://context7.com/well-typed/falsify/llms.txt

Derive generators automatically using the GenDefault typeclass with DerivingVia helpers. This simplifies the creation of generators for custom data types.

```haskell
{-# LANGUAGE DerivingVia #}
{-# LANGUAGE DeriveGeneric #}

import GHC.Generics (Generic)
import Test.Falsify.GenDefault
import Test.Falsify.GenDefault.Std (Std)
import qualified Test.Falsify.Generator as Gen

-- Derive generator via Generic
data Person = Person { name :: String, age :: Int }
  deriving stock (Show, Generic)
  deriving GenDefault Std via ViaGeneric Std Person

-- Derive generator for integral types
newtype Age = Age Int
  deriving newtype (Show, Bounded, Integral, Real, Enum, Num, Ord, Eq, FiniteBits)
  deriving GenDefault tag via ViaIntegral Int

-- Derive generator for enum types
data Color = Red | Green | Blue
  deriving stock (Show, Enum, Bounded)
  deriving GenDefault tag via ViaEnum Color

-- Use in tests
prop_person :: Property ()
prop_person = do
    person <- gen $ genDefault @Std Proxy
    info $ "Generated: " ++ show (person :: Person)
    return ()
```

--------------------------------

### Generate Lists with Controlled Length and Shrinking in Haskell

Source: https://context7.com/well-typed/falsify/llms.txt

This code demonstrates generating lists with Falsify, allowing control over list length and providing automatic shrinking capabilities. The generator shrinks the list length towards the origin and can drop elements, preferring to remove them from the end.

```haskell
import Data.Word
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range

-- Generate list of 0-10 integers
genShortList :: Gen [Int]
genShortList = Gen.list (Range.between (0, 10)) $ Gen.int (Range.between (0, 100))

-- Generate non-empty list
genNonEmptyList :: Gen [Int]
genNonEmptyList = Gen.list (Range.between (1, 50)) $ Gen.int (Range.withOrigin (-100, 100) 0)

-- Shrinking behavior: length shrinks towards origin, elements can be dropped
-- from any position (preferring end), and remaining elements shrink independently

```

--------------------------------

### Generate Binary Trees with Shrinking (Haskell)

Source: https://context7.com/well-typed/falsify/llms.txt

Generates binary trees with controlled size and proper shrinking behavior. It also supports the generation of binary search trees with specified interval constraints. The `Tree` data type and associated generators are provided for this purpose.

```haskell
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range
import Data.Falsify.Tree (Tree(..))

-- Generate binary tree with 0-20 nodes
genTree :: Gen (Tree Int)
genTree = Gen.tree (Range.between (0, 20)) $ Gen.int (Range.between (0, 100))

-- Generate binary search tree in interval [0, 100]
genBST :: Gen (Tree (Int, ()))
genBST = Gen.bst (\_ -> pure ()) (Interval (Inclusive 0) (Inclusive 100))
```

--------------------------------

### Generate Functions for Testing (Haskell)

Source: https://context7.com/well-typed/falsify/llms.txt

Generates random functions that can be tested and shrunk. It utilizes pattern synonyms like `Fn`, `Fn2`, and `Fn3` for convenient extraction of functions with one, two, or three arguments, respectively. These generated functions can then be used within property-based tests.

```haskell
import Test.Tasty.Falsify
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range

prop_function :: Property ()
prop_function = do
    -- Generate a function Int -> Bool
    Fn (f :: Int -> Bool) <- gen $ Gen.fun $ Gen.bool False

    -- Generate a two-argument function
    Fn2 (g :: Int -> Int -> Int) <- gen $ Gen.fun $ Gen.int (Range.between (0, 10))

    -- Use the functions in assertions
    let x = 5
    info $ "f(" ++ show x ++ ") = " ++ show (f x)
    info $ "g(1, 2) = " ++ show (g 1 2)
    return ()
```

--------------------------------

### Test Property with Tasty Integration in Haskell

Source: https://context7.com/well-typed/falsify/llms.txt

This snippet demonstrates how to create property-based tests using Falsify's integration with the tasty test framework. It defines a property that checks if reversing a list twice results in the original list and uses generators for lists and integers.

```haskell
import Test.Tasty
import Test.Tasty.Falsify
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range
import qualified Prelude as P

main :: IO ()
main = defaultMain $ testGroup "MyTests" [
    testProperty "reverse is involutive" $ do
      xs <- gen $ Gen.list (Range.between (0, 100)) (Gen.int (Range.between (0, 100)))
      assert $ P.eq .$ ("reversed twice", reverse (reverse xs)) .$ ("original", xs)
  ]

```

--------------------------------

### Generate Booleans with Target Shrinking in Haskell

Source: https://context7.com/well-typed/falsify/llms.txt

This snippet shows how to generate boolean values using Falsify, with the ability to shrink towards a specified target value (either `True` or `False`). Each value is chosen with equal probability.

```haskell
import qualified Test.Falsify.Generator as Gen

-- Generate bool, shrinks towards True
genBoolToTrue :: Gen Bool
genBoolToTrue = Gen.bool True

-- Generate bool, shrinks towards False
genBoolToFalse :: Gen Bool
genBoolToFalse = Gen.bool False

```

--------------------------------

### Override Shrinking Behavior

Source: https://context7.com/well-typed/falsify/llms.txt

Control shrinking with explicit overrides when default behavior is not desired. This allows for precise control over how generated values are reduced.

```haskell
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range

-- Disable shrinking entirely
genNoShrink :: Gen Int
genNoShrink = Gen.withoutShrinking $ Gen.int (Range.between (0, 100))

-- Shrink to specific values only
genShrinkToSpecific :: Gen Int
genShrinkToSpecific = Gen.shrinkToOneOf [0, 50, 100] $
    Gen.int (Range.between (0, 100))

-- Start with one value, then allow others
genFirstThen :: Gen Int
genFirstThen = Gen.firstThen id (const 0) <*> Gen.int (Range.between (1, 100))
-- Initially generates from range, but first shrink step goes to 0
```

--------------------------------

### Generate Random Elements from List (Haskell)

Source: https://context7.com/well-typed/falsify/llms.txt

Generates random elements from lists, with a bias towards earlier elements for shrinking. Supports picking single elements and elements with context (before, element, after). Also includes functionality to shuffle a list.

```haskell
import Data.List.NonEmpty (NonEmpty(..))
import qualified Test.Falsify.Generator as Gen

-- Pick element from non-empty list, shrinks towards earlier elements
genElement :: Gen Char
genElement = Gen.elem $ 'a' :| ['b', 'c', 'd', 'e']

-- Pick with context (before, element, after)
genWithContext :: Gen ([Int], Int, [Int])
genWithContext = Gen.pick $ 1 :| [2, 3, 4, 5]

-- Shuffle a list (generate permutation)
genShuffled :: Gen [Int]
genShuffled = Gen.shuffle [1, 2, 3, 4, 5]
```

--------------------------------

### Test Shrinking Behavior (Haskell)

Source: https://context7.com/well-typed/falsify/llms.txt

Verifies that generators shrink correctly towards smaller or more canonical values. It provides functions like `testShrinkingOfGen` to check if shrinking adheres to a given predicate and `testMinimum` to validate the smallest counterexample found.

```haskell
import Test.Tasty.Falsify
import qualified Test.Falsify.Predicate as P
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range

-- Test that shrinking moves towards smaller values
prop_shrinking :: Property ()
prop_shrinking = do
    testShrinkingOfGen P.ge $ Gen.int (Range.between (0, 100))
    -- Verifies: for each shrink step, new value >= old value (moving towards origin 0)

-- Test the minimum counterexample found
prop_minimum :: Property ()
prop_minimum =
    testMinimum (P.expect [1, 0]) $ do
      xs <- gen $ Gen.list (Range.between (0, 10)) (Gen.int (Range.between (0, 1)))
      case xs of
        (a:b:_) | a /= b -> testFailed xs
        _ -> return ()

```

--------------------------------

### Assert Properties with Predicates (Haskell)

Source: https://context7.com/well-typed/falsify/llms.txt

Uses the predicate system for assertions, providing informative error messages and clear failure diagnostics. Predicates can be composed and chained using the `.$` operator. Supports various built-in predicates like equality, ordering, and custom function checks.

```haskell
import Test.Tasty.Falsify
import Test.Falsify.Predicate ((.$))
import qualified Test.Falsify.Predicate as P
import qualified Test.Falsify.Generator as Gen
import qualified Test.Falsify.Range as Range
import Data.List (sort)

prop_predicates :: Property ()
prop_predicates = do
    x <- gen $ Gen.int $ Range.withOrigin (-100, 100) 0
    y <- gen $ Gen.int $ Range.withOrigin (-100, 100) 0

    -- Equality check
    assert $ P.eq .$ ("x + y", x + y) .$ ("y + x", y + x)

    -- Ordering checks
    assert $ P.le .$ ("x", x) .$ ("upper", 100)
    assert $ P.ge .$ ("x", x) .$ ("lower", -100)

    -- Custom predicate with function composition
    assert $ P.even `P.dot` P.fn ("double", (* 2)) .$ ("x", x)

    -- Pairwise predicate on lists
    xs <- gen $ Gen.list (Range.between (1, 10)) $ Gen.int (Range.between (0, 10))
    -- Check all consecutive pairs satisfy <=
    assert $ P.pairwise P.le .$ ("sorted xs", sort xs)

-- Available predicates: eq, ne, lt, le, gt, ge, even, odd, elem, between, expect
```
Tokens:
Raw