Property Testing

LivestockAI uses property-based testing (PBT) with fast-check to validate business logic invariants.

What is Property Testing?

Instead of testing specific examples, property tests verify that properties hold for ALL possible inputs:

typescript
1// Example-based test
2it('calculates FCR correctly', () => {
3  expect(calculateFCR(150, 100)).toBe(1.5)
4})
5
6// Property-based test
7it('FCR is always positive when inputs are positive', () => {
8  fc.assert(
9    fc.property(
10      fc.float({ min: 0.1, max: 10000 }),
11      fc.float({ min: 0.1, max: 10000 }),
12      (feed, weight) => {
13        const fcr = calculateFCR(feed, weight)
14        return fcr === null || fcr > 0
15      },
16    ),
17  )
18})

fast-check Basics

typescript
1import { describe, it, expect } from 'vitest'
2import * as fc from 'fast-check'
3
4describe('Property Tests', () => {
5  it('property holds for all inputs', () => {
6    fc.assert(
7      fc.property(fc.integer({ min: 1, max: 100000 }), (quantity) => {
8        // Property must return true or throw
9        return quantity > 0
10      }),
11      { numRuns: 100 },
12    )
13  })
14})

Common Arbitraries

typescript
1// Integers
2fc.integer({ min: 1, max: 100000 })
3fc.nat() // Non-negative integer
4
5// Floats
6fc.float({ min: 0, max: 10000 })
7
8// Strings
9fc.string()
10fc.uuid()
11
12// Arrays
13fc.array(fc.integer(), { minLength: 0, maxLength: 20 })
14
15// Objects
16fc.record({
17  quantity: fc.integer({ min: 1, max: 1000 }),
18  price: fc.float({ min: 0, max: 10000 }),
19})

Inventory Invariant Example

From tests/features/batches/batches.property.test.ts:

typescript
1/**
2 * Property 4: Inventory Invariant
3 * For any batch, current_quantity SHALL always equal:
4 * initial_quantity - sum(mortality) - sum(sales)
5 */
6describe('Property 4: Inventory Invariant', () => {
7  it('current_quantity equals initial - mortalities - sales', () => {
8    fc.assert(
9      fc.property(
10        fc.integer({ min: 1, max: 100000 }),
11        fc.array(fc.integer({ min: 1, max: 1000 })),
12        fc.array(fc.integer({ min: 1, max: 1000 })),
13        (initial, mortalities, sales) => {
14          const { constrained } = constrainQuantities(
15            initial,
16            mortalities,
17            sales,
18          )
19          const current = calculateCurrentQuantity(initial, constrained)
20
21          expect(current).toBeGreaterThanOrEqual(0)
22          expect(current).toBeLessThanOrEqual(initial)
23        },
24      ),
25      { numRuns: 100 },
26    )
27  })
28})

Linking to Requirements

Annotate tests with requirement links:

typescript
1/**
2 * **Validates: Requirements 3.2, 4.2, 8.2**
3 */
4it('inventory invariant holds', () => {
5  // ...
6})

When to Use Property Testing

• Mathematical calculations (FCR, mortality rate, profit)
• Invariants (quantity never negative, totals match)
• State transitions (batch status changes)
• Data transformations (currency conversion)

Related Skills

• vitest-patterns - Unit testing basics
• three-layer-architecture - Service layer testing