PropertyBased

https://github.com/x-sheep/swift-property-based
Admin
PropertyBased is a Swift 6 library that enables property-based testing in swift-testing, similar to...
Tokens:6,587
Snippets:67
Trust Score:7.6
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Swift Package Dependency

Source: https://github.com/x-sheep/swift-property-based/blob/main/README.md

Add this line to your Package.swift dependencies array when creating a Swift package.

```swift
.package(url: "https://github.com/x-sheep/swift-property-based.git", from: "1.0.0")
```

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

### Boolean Generator Examples

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Shows how to generate random boolean values using `Gen.bool`. The default generator provides a 50/50 true/false distribution, which can be customized with a probability rate.

```swift
import PropertyBased

// Default 50/50 distribution
let coinFlip = Gen.bool

// Custom probability (80% true)
let mostlyTrue = Gen.bool(0.8)

// Usage in a property check
@Test func testBooleanLogic() async {
    await propertyCheck(input: Gen.bool, Gen.bool) { a, b in
        #expect((a && b) == (b && a))  // Commutativity
        #expect(!(a && b) == (!a || !b))  // De Morgan's law
    }
}
```

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

### Property Check with Input Shrinking

Source: https://github.com/x-sheep/swift-property-based/blob/main/README.md

Example demonstrating input shrinking for a test that checks if the sum of numbers in an array is below a threshold. Shrinking helps find the smallest failing input.

```swift
@Test func checkSumInRange() async {
  await propertyCheck(input: Gen.int(in: 0...100).array(of: 1...10)) { numbers in
    let sum = numbers.reduce(0, +)
    #expect(sum < 250)
  }
}
```

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

### Integer Generator Examples

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Demonstrates various ways to generate random integers using `Gen.int` and its type-specific variants like `Gen.int8` and `Gen.uint`. Supports closed, partial, and specific integer type ranges.

```swift
import PropertyBased

// Generate integers in a closed range
let smallInt = Gen.int(in: 0...100)
let negativeInt = Gen.int(in: -50...50)

// Generate integers with partial ranges
let positiveInt = Gen.int(in: 1...)
let boundedAbove = Gen.int(in: ...1000)

// Generate specific integer types
let byte = Gen.int8(in: 0...127)
let unsigned = Gen.uint(in: 0...1000)
let bigInt = Gen.int64(in: .min ... .max)

// Usage in a property check
@Test func testAbsoluteValue() async {
    await propertyCheck(input: Gen.int(in: -1000...1000)) { n in
        #expect(abs(n) >= 0)
        #expect(abs(n) == abs(-n))
    }
}
```

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

### Basic Property Check Example

Source: https://github.com/x-sheep/swift-property-based/blob/main/README.md

A simple property-based test checking if n + n equals n * 2 for integers within a specified range.

```swift
import Testing
import PropertyBased

@Test func testDuplication() async {
  await propertyCheck(input: Gen.int(in: 0...100)) { n in
    #expect(n + n == n * 2)
  }
}
```

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

### Floating Point Generator Examples

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Illustrates the use of `Gen.float` and `Gen.double` for generating random floating-point numbers. Supports various range types, including half-open ranges and `CGFloat`.

```swift
import PropertyBased

// Generate floats in ranges
let probability = Gen.float(in: 0.0...1.0)
let temperature = Gen.double(in: -40.0...50.0)

// Half-open ranges
let normalized = Gen.double(in: 0.0..<1.0)

// CGFloat for UI work (requires Foundation)
let opacity = Gen.cgFloat(in: 0.0...1.0)

// Usage in a property check
@Test func testFloatArithmetic() async {
    await propertyCheck(input: Gen.double(in: 1.0...1000.0)) { x in
        let sqrt_x = x.squareRoot()
        #expect(abs(sqrt_x * sqrt_x - x) < 0.0001)
    }
}
```

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

### Property Check with Multiple Inputs and Custom Count

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Perform property checks with multiple inputs and specify a custom iteration count using the `count` parameter. This example tests string repetition and its length.

```swift
import Testing
import PropertyBased

// Property check with multiple inputs and custom iteration count
@Test func testStringConcatenation() async {
    await propertyCheck(count: 500, input: Gen.letterOrNumber.string(of: 1...10), Gen.int(in: 0...5)) { str, n in
        let repeated = String(repeating: str, count: n)
        #expect(repeated.count == str.count * n)
    }
}
```

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

### Reproducing Failing Test Cases with Fixed Seed

Source: https://github.com/x-sheep/swift-property-based/blob/main/README.md

Shows how to use a fixed seed to reliably reproduce a failing test case. This is useful when a test fails intermittently.

```swift
@Test(.fixedSeed("aKPPWDEafU0CGMDYHef/ETcbYUyjWQvRVP1DTNy6qJk="))
func failsSometimes() async {
  await propertyCheck(input: Gen.int(in: 0...1000)) { n in
    #expect(n < 990)
  }
}
```

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

### Use Custom Int256 Generator

Source: https://github.com/x-sheep/swift-property-based/blob/main/Sources/PropertyBased/Documentation.docc/Gen.md

Demonstrates how to use the custom `int256()` generator after it has been defined. This is the call site usage for the extended generator.

```swift
Gen.int256()
```

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

### Combining Generators with zip

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Combine multiple generators into a single generator that produces tuples. `zip` supports composed shrinking and can be combined with `map` to create custom types.

```swift
import PropertyBased

// Combine two generators
let pointGen = zip(
    Gen.int(in: -100...100),
    Gen.int(in: -100...100)
)

// Combine three generators
let colorGen = zip(
    Gen.int(in: 0...255),
    Gen.int(in: 0...255),
    Gen.int(in: 0...255)
)

// Combine with map for custom types
struct Point { let x: Int; let y: Int }

let typedPointGen = zip(
    Gen.int(in: -100...100),
    Gen.int(in: -100...100)
).map { Point(x: $0, y: $1) }
```

```swift
// Usage in a property check
@Test func testPointDistance() async {
    await propertyCheck(input: pointGen, pointGen) { p1, p2 in
        let distance = sqrt(Double((p1.0 - p2.0) * (p1.0 - p2.0) + (p1.1 - p2.1) * (p1.1 - p2.1)))
        #expect(distance >= 0)
    }
}
```

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

### Enable Input Shrinking with .shrinking

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Enable shrinking for a single test, an entire test suite, or disable it for specific tests within a suite. Shrinking automatically reduces failing inputs to their minimal form, aiding debugging.

```swift
import Testing
import PropertyBased

// Enable shrinking for a single test
@Test(.shrinking) func testWithShrinking() async {
    await propertyCheck(input: Gen.int(in: 0...100).array(of: 1...10)) {
        let sum = numbers.reduce(0, +)
        #expect(sum < 250)
    }
}
// Without shrinking: "Failure occured with input [63, 61, 33, 53, 97, 68, 23, 16]"
// With shrinking: "Failure occured with input [46, 97, 68, 23, 16]" (shrunk to minimal sum of 250)

// Enable shrinking for an entire test suite
@Suite(.shrinking)
struct MyPropertyTests {
    @Test func testOne() async {
        await propertyCheck(input: Gen.int(in: 0...1000)) {
            #expect(n < 500)
        }
    }
}

// Disable shrinking for specific tests within an enabled suite
@Suite(.shrinking)
struct MixedTests {
    @Test(.shrinking(false)) func testWithoutShrinking() async {
        // Shrinking disabled for this test
    }
}
```

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

### Create Custom Generators in Swift

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Extend the `Gen` namespace or use the `Generator` initializer to create custom generators for specific types or with custom shrinking logic. This allows for more tailored property-based testing.

```swift
import PropertyBased

// Extend Gen namespace for custom types
struct UserId: Hashable {
    let value: Int
}

extension Gen where Value == UserId {
    static func userId() -> Generator<UserId, some Sequence> {
        Gen.int(in: 1...1_000_000).map { UserId(value: $0) }
    }
}

// Create generator with custom shrinking
extension Gen where Value == Int {
    static func positiveEven(in range: ClosedRange<Int>) -> Generator<Int, some Sequence> {
        Generator(
            run: { rng in
                let value = Int.random(in: range, using: &rng)
                return value - (value % 2)  // Make even
            },
            shrink: {
                // Shrink toward 0 in steps of 2
                stride(from: value - 2, through: max(0, range.lowerBound), by: -2)
            }
        )
    }
}

// Usage
@Test func testCustomGenerators() async {
    await propertyCheck(input: Gen.userId()) {
        #expect(userId.value > 0)
    }

    await propertyCheck(input: Gen.positiveEven(in: 0...100)) {
        #expect(n % 2 == 0)
    }
}
```

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

### Property Check with Multiple Inputs and Custom Repeat Count

Source: https://github.com/x-sheep/swift-property-based/blob/main/README.md

Demonstrates property-based testing with multiple inputs: a generated string and an integer for repetition count. Includes a custom repeat count for the test.

```swift
import Testing
import PropertyBased

let stringCreator: Generator<String, some Sequence> = Gen.letterOrNumber.string(of: 1...10)

@Test func testStringRepeat() async {
  await propertyCheck(count: 500, input: stringCreator, Gen.int(in: 0...5)) { str, n in
    let actual = String(repeating: str, count: n)
    #expect(actual.length == str.length * n)
  }
}
```

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

### Optional Value Generation with Gen.optional

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Generate optional values using `.optional` on a generator. Configure the probability of generating a value versus `nil` using `valueRate`.

```swift
import PropertyBased

// Default 75% value, 25% nil
let optionalInt = Gen.int(in: 0...100).optional

// Custom rate (90% value, 10% nil)
let mostlyPresent = Gen.int(in: 0...100).optional(valueRate: 0.9)
```

```swift
// Usage in a property check
@Test func testOptionalHandling() async {
    await propertyCheck(input: Gen.int(in: 0...100).optional) { maybeNumber in
        if let number = maybeNumber {
            #expect(number >= 0 && number <= 100)
        }
        // nil case is valid too
    }
}
```

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

### Generate OptionSet Combinations in Swift

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Generate random `OptionSet` combinations. `Gen.optionSet` generates any combination, while `Gen.optionSet(of:)` restricts generation to a specified set of options.

```swift
import PropertyBased

struct Permissions: OptionSet {
    var rawValue: UInt8

    static let read = Permissions(rawValue: 1 << 0)
    static let write = Permissions(rawValue: 1 << 1)
    static let execute = Permissions(rawValue: 1 << 2)
    static let all: Permissions = [.read, .write, .execute]
}

// Generate any combination of bits
let anyPermissions = Gen<Permissions>.optionSet

// Generate only from specified options
let validPermissions = Gen.optionSet(of: Permissions.all)
```

```swift
@Test func testPermissions() async {
    await propertyCheck(input: Gen.optionSet(of: Permissions.all)) { perms in
        if perms.contains(.write) {
            // Write implies read in our system
            let withRead = perms.union(.read)
            #expect(withRead.contains(.read))
        }
    }
}
```

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

### Date and DateTime Generation

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Generate random dates and datetimes with or without time components. Generators automatically shrink towards the current date. Specify year or date ranges for more control.

```swift
import PropertyBased
import Foundation

// Date without time (UTC)
let anyDate = Gen.date
let dateIn2024 = Gen.date(inYear: 2024)
let dateInRange = Gen.date(in: "2020-01-01"..."2025-12-31")

// Date with time components
let anyDateTime = Gen.dateTime
let dateTimeIn2024 = Gen.dateTime(inYear: 2024)
let dateTimeInRange = Gen.dateTime(in: "2024-01-01"..<"2025-01-01")

// Year generator
let yearGen = Gen.year  // ~60 years past to ~60 years future
let specificYears = Gen.year(in: 2000...2030)
```

```swift
// Usage in a property check
@Test func testDateComparison() async {
    await propertyCheck(input: Gen.date(inYear: 2024), Gen.date(inYear: 2024)) { date1, date2 in
        if date1 < date2 {
            #expect(date1.timeIntervalSince1970 < date2.timeIntervalSince1970)
        }
    }
}
```

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

### Generate Random Collections in Swift

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Create generators for arrays, sets, and dictionaries with configurable sizes and element types. Sets may contain fewer elements than specified due to duplicate removal.

```swift
import PropertyBased

// Array generators
let intArray = Gen.int(in: 0...100).array(of: 1...10)
let fixedSizeArray = Gen.bool.array(of: 5)

// Set generators (may have fewer elements due to duplicates)
let intSet = Gen.int(in: 0...100).set(ofAtMost: 1...10)

// Dictionary generators using zip
let stringToInt = zip(
    Gen.letter.string(of: 1...5),
    Gen.int(in: 0...100)
).dictionary(ofAtMost: 1...5)
```

```swift
@Test func testCollectionProperties() async {
    await propertyCheck(input: Gen.int(in: -100...100).array(of: 0...20)) { numbers in
        let sorted = numbers.sorted()
        #expect(sorted.count == numbers.count)

        for i in 0..<(sorted.count - 1) {
            #expect(sorted[i] <= sorted[i + 1])
        }
    }
}
```

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

### Add PropertyBased to Test Target

Source: https://github.com/x-sheep/swift-property-based/blob/main/README.md

Include the PropertyBased product in your test target's dependencies in Package.swift.

```swift
dependencies: [
  .product(name: "PropertyBased", package: "swift-property-based"),
]
```

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

### Reproduce Failing Tests with .fixedSeed

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Use the `.fixedSeed` trait with a provided seed string or raw integer values to reproduce specific failing test cases. This is crucial for debugging intermittent failures.

```swift
import Testing
import PropertyBased

// When a test fails, PropertyBased outputs:
// "Failure occured with input 992.
//  Add `.fixedSeed("aKPPWDEafU0CGMDYHef/ETcbYUyjWQvRVP1DTNy6qJk=")` to the Test to reproduce this issue."

// Add the seed to reproduce the failure
@Test(.fixedSeed("aKPPWDEafU0CGMDYHef/ETcbYUyjWQvRVP1DTNy6qJk="))
func failsReproducibly() async {
    await propertyCheck(input: Gen.int(in: 0...1000)) {
        #expect(n < 990)
    }
}

// Alternative: Use raw UInt64 values (works on platforms without Foundation)
@Test(.fixedSeed(123456789, 987654321, 111111111, 222222222))
func failsWithRawSeed() async {
    await propertyCheck(input: Gen.int(in: 0...1000)) {
        #expect(n < 990)
    }
}
```

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

### Basic Property Check with Single Input

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Use `propertyCheck` with a single integer input to verify a mathematical property. The generator `Gen.int(in: 0...100)` provides integers within the specified range.

```swift
import Testing
import PropertyBased

// Basic property check with a single input
@Test func testMultiplicationProperty() async {
    await propertyCheck(input: Gen.int(in: 0...100)) { n in
        #expect(n + n == n * 2)
    }
}
```

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

### Extend Gen with Custom Int256 Generator

Source: https://github.com/x-sheep/swift-property-based/blob/main/Sources/PropertyBased/Documentation.docc/Gen.md

This snippet shows how to extend the `Gen` namespace to create a custom generator for a `Int256` type. This allows for property-based testing of custom types by defining a new generator function.

```swift
extension Gen where Value == Int256 {
    static func int256() -> Generator<Int256, Shrink.Integer<Int256>> {
        Gen<Int256>.value()
    }
}
```

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

### Select Elements and Shuffle Collections in Swift

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Use `Gen.element` to pick a random item from a collection or `Gen.shuffled` to create a randomly ordered version of an array. The shuffle property check verifies that all original elements are present.

```swift
import PropertyBased

// Pick random element from a collection
let colorGen = Gen<String?>.element(of: ["red", "green", "blue", "yellow"])

// Create shuffled arrays
let shuffledNumbers = Gen<[Int]>.shuffled([1, 2, 3, 4, 5])
```

```swift
@Test func testShufflePreservesElements() async {
    let original = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

    await propertyCheck(input: Gen.shuffled(original)) { shuffled in
        #expect(Set(shuffled) == Set(original))
        #expect(shuffled.count == original.count)
    }
}
```

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

### Generate Random Characters and Strings in Swift

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Use predefined generators for digits, letters, ASCII, and Latin-1 characters, or create custom ranges. Strings can be generated with specified length ranges.

```swift
import PropertyBased

// Character generators
let digit = Gen.number           // '0'...'9'
let lowercase = Gen.lowercaseLetter  // 'a'...'z'
let uppercase = Gen.uppercaseLetter  // 'A'...'Z'
let letter = Gen.letter          // 'a'...'z', 'A'...'Z'
let alphanumeric = Gen.letterOrNumber
let asciiChar = Gen.ascii
let latin1Char = Gen.latin1

// Custom character ranges
let hexDigit = Gen.character(in: "0"..."9")

// String generators with length ranges
let username = Gen.letterOrNumber.string(of: 3...20)
let fixedLengthCode = Gen.number.string(of: 6)
let password = Gen.ascii.string(of: 8...32)
```

```swift
@Test func testStringOperations() async {
    let stringGen = Gen.lowercaseLetter.string(of: 1...10)

    await propertyCheck(input: stringGen) { str in
        #expect(str.uppercased().lowercased() == str)
        #expect(str.count == str.reversed().count)
    }
}
```

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

### Weighted Selection with Gen.oneOf and Gen.frequency

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Use `Gen.oneOf` for equal probability selection between generators and `Gen.frequency` for weighted selection. This is useful for generating enums with associated values.

```swift
import PropertyBased

enum Result {
    case success(Int)
    case failure(String)
    case pending
}

// Equal probability selection
let resultGen = Gen<Result>.oneOf(
    Gen.always(.pending).eraseToAnySequence(),
    Gen.int(in: 0...100).map(Result.success).eraseToAnySequence(),
    Gen.lowercaseLetter.string(of: 5...20).map(Result.failure).eraseToAnySequence()
)

// Weighted probability selection (weights: 0.5, 1.0, 2.0)
let weightedResultGen = Gen<Result>.frequency(
    (0.5, Gen.always(.pending).eraseToAnySequence()),
    (1.0, Gen.int(in: 0...100).map(Result.success).eraseToAnySequence()),
    (2.0, Gen.lowercaseLetter.string(of: 5...20).map(Result.failure).eraseToAnySequence())
)
```

```swift
// Usage in a property check
@Test func testResultHandling() async {
    await propertyCheck(input: resultGen) { result in
        switch result {
        case .success(let value):
            #expect(value >= 0 && value <= 100)
        case .failure(let message):
            #expect(!message.isEmpty)
        case .pending:
            break
        }
    }
}
```

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

### Generator Transformations: map, compactMap, filter

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Transform generator output using functional operations like `map`, `compactMap`, and `filter` while preserving shrinking behavior. `map` transforms values, `compactMap` filters and transforms, and `filter` restricts values.

```swift
import PropertyBased

// Map to transform values
let evenNumbers = Gen.int(in: 0...50).map { $0 * 2 }

// CompactMap to filter and transform
let positiveSquareRoots = Gen.int(in: -100...100).compactMap {
    $0 >= 0 ? sqrt(Double($0)) : nil
}

// Filter to restrict values
let oddNumbers = Gen.int(in: 0...100).filter { $0 % 2 == 1 }

// Map tuples with two-argument closure
let sumGen = zip(Gen.int(in: 0...50), Gen.int(in: 0...50)).map { $0 + $1 }
```

```swift
// Usage in a property check
@Test func testTransformedGenerators() async {
    let nonEmptyString = Gen.letterOrNumber.string(of: 1...20)
        .filter { !$0.isEmpty }

    await propertyCheck(input: nonEmptyString) { str in
        #expect(!str.isEmpty)
        #expect(str.first != nil)
    }
}
```

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

### Property Check with Array Input

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Test properties of array manipulations, such as reversing an array twice. The `array(of:)` generator creates arrays with elements within a specified range and size.

```swift
import Testing
import PropertyBased

// Property check with array input
@Test func testArrayReverse() async {
    await propertyCheck(input: Gen.int(in: -100...100).array(of: 0...20)) { numbers in
        #expect(numbers.reversed().reversed() == Array(numbers))
    }
}
```

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

### Generate Enum Cases in Swift

Source: https://context7.com/x-sheep/swift-property-based/llms.txt

Generate random enum cases for enums conforming to `CaseIterable`. This is useful for testing different states or variations of an enum.

```swift
import PropertyBased

enum Direction: CaseIterable {
    case north, south, east, west
}

enum Priority: Int, CaseIterable {
    case low = 1, medium = 2, high = 3
}

// Generate random enum cases
let directionGen = Gen<Direction>.case
let priorityGen = Gen<Priority>.case
```

```swift
@Test func testEnumHandling() async {
    await propertyCheck(input: Gen<Direction>.case) { direction in
        let opposite: Direction = switch direction {
            case .north: .south
            case .south: .north
            case .east: .west
            case .west: .east
        }
        #expect(direction != opposite)
    }
}
```
Tokens:
Raw