testing-property-based-fast-check

name	testing-property-based-fast-check
description	Property-based testing con fast-check: generar miles de inputs aleatorios para validar propiedades invariantes. Integración con Jest, arbitraries custom, model-based testing, detección de race conditions.
version	1.0.0
author	Mastermind

Property-Based Testing con fast-check

Framework de testing basado en propiedades que genera miles de inputs aleatorios para verificar que ciertas invariantes se mantienen siempre. Inspirado en QuickCheck (Haskell).

¿Qué es y por qué importa?

El testing tradicional usa ejemplos concretos: expect(f(2)).toBe(4). El property-based testing dice: "para TODOS los enteros positivos x, f(x) debe ser >= x". fast-check genera automáticamente miles de inputs aleatorios y verifica la propiedad. Si falla, hace shrinking automático para encontrar el contraejemplo más pequeño posible.

Datos reales: fast-check tiene 5k+ estrellas en GitHub, es usado por Jest, Jasmine, Ramda, fp-ts, io-ts. Encontró bugs reales en Jest y query-string.

Instalación

npm install --save-dev fast-check

Patrón básico: propiedades

const fc = require('fast-check');

// Propiedad: una cadena siempre se contiene a sí misma
describe('string properties', () => {
  it('should always contain itself', () => {
    fc.assert(
      fc.property(fc.string(), (text) => {
        return text.includes(text);
      }),
    );
  });

  // Propiedad: concatenar a+b+c siempre contiene b
  it('should always contain its substrings', () => {
    fc.assert(
      fc.property(fc.string(), fc.string(), fc.string(), (a, b, c) => {
        return (a + b + c).includes(b);
      }),
    );
  });
});

Arbitraries integrados (los más útiles)

// Números
fc.integer()              // -2³¹ a 2³¹-1
fc.integer({ min: 0, max: 100 })
fc.float()                // float de punto flotante
fc.double()               // double precision
fc.bigInt({ min: 0n, max: 1000n })

// Strings
fc.string()               // cualquier string
fc.string({ minLength: 1, maxLength: 50 })
fc.asciiString()          // solo ASCII imprimible
fc.hexaString({ minLength: 6, maxLength: 6 })  // #FFFFFF
fc.fullUnicodeString()

// Arrays
fc.array(fc.integer())
fc.array(fc.string(), { minLength: 1, maxLength: 10 })
fc.uniqueArray(fc.integer(), { minLength: 3, maxLength: 10 })

// Combinaciones
fc.oneof(fc.string(), fc.integer())
fc.constant('fixed value')
fc.constantFrom('red', 'green', 'blue')
fc.option(fc.string())    // string | null
fc.nat()                  // entero no negativo

Arbitraries custom con fc.record y fc.dictionary

// Objeto con campos tipados
const userArbitrary = fc.record({
  id: fc.integer({ min: 1 }),
  name: fc.string({ minLength: 1, maxLength: 50 }),
  email: fc.string().filter(s => s.includes('@')),
  age: fc.integer({ min: 0, max: 150 }),
});

// Propiedad sobre usuarios
it('user age should be valid', () => {
  fc.assert(
    fc.property(userArbitrary, (user) => {
      expect(user.age >= 0 && user.age <= 150).toBe(true);
    }),
  );
});

// Diccionario: string → T
const stringToNumber = fc.dictionary(fc.string(), fc.integer());

Precondiciones con fc.pre()

it('reverse of reverse is identity (only for non-empty)', () => {
  fc.assert(
    fc.property(fc.string(), (text) => {
      fc.pre(text.length > 0);  // solo ejecutar si precondición se cumple
      return reverse(reverse(text)) === text;
    }),
  );
});

Gen: composición de arbitraries

// Generar datos complejos con lógica condicional
const userWithOrders = fc.gen(() => {
  const userId = yield* fc.integer({ min: 1 });
  const name = yield* fc.string({ maxLength: 30 });
  const orderCount = yield* fc.integer({ min: 0, max: 10 });
  const orders = yield* fc.array(
    fc.record({
      id: fc.integer({ min: 1 }),
      amount: fc.float({ min: 0.01, max: 10000 }),
    }),
    { minLength: orderCount, maxLength: orderCount }
  );
  return { userId, name, orders };
});

Integración con Jest

const fc = require('fast-check');

describe('convertEsiosValue', () => {
  it('should divide by 10 for indicators with factor 10', () => {
    fc.assert(
      fc.property(fc.integer({ min: 0, max: 100000 }), (raw) => {
        const result = convertEsiosValue(raw, 10);
        expect(result).toBe(raw / 10);
      }),
    );
  });

  it('should handle zero values', () => {
    fc.assert(
      fc.property(fc.integer(), (raw) => {
        const result = convertEsiosValue(0, 10);
        expect(result).toBe(0);
      }),
    );
  });
});

Ejemplo práctico: conversión de unidades ESIOS

describe('ESIOS unit conversion properties', () => {
  // Propiedad: aplicar conversión y luego inversa da el valor original
  it('conversion should be invertible', () => {
    fc.assert(
      fc.property(
        fc.integer({ min: 0, max: 1000000 }),
        fc.constantFrom([1, 10, 100, 1000, 10000]),
        (raw, factor) => {
          const converted = Math.floor(raw / factor);
          const restored = converted * factor;
          // La restauración puede perder precisión (floor), pero nunca excede
          expect(restored).toBeLessThanOrEqual(raw);
        },
      ),
    );
  });

  // Propiedad: sumar demanda total nunca excede producción total + importaciones
  it('demand should not exceed supply', () => {
    fc.assert(
      fc.property(
        fc.array(fc.integer({ min: 0, max: 100000 }), { minLength: 1 }),
        fc.integer({ min: 0, max: 100000 }),
        (sources, demand) => {
          const total = sources.reduce((a, b) => a + b, 0);
          // En un sistema real: demand <= total
          expect(demand <= total).toBe(true);
        },
      ),
    );
  });
});

Model-based testing (avanzado)

// Simular un estado y verificar transiciones
const counterModel = fc.model(
  fc.constantFrom('increment', 'decrement', 'reset'),
  {
    init: () => ({ value: 0 }),
    run: (state, action) => {
      switch (action) {
        case 'increment': return { ...state, value: state.value + 1 };
        case 'decrement': return { ...state, value: state.value - 1 };
        case 'reset': return { ...state, value: 0 };
      }
    },
    // Propiedad que debe mantenerse en cada estado
    assert: (state, executed) => {
      // El valor nunca puede ser negativo si solo hay incrementos
      // (esto se verifica en el runner)
    },
  },
  { preconditions: () => true },
);

fc.assert(fc.modelVerify(counterModel));

Detección de race conditions

// fast-check puede desordenar promesas para detectar races
it('should handle concurrent operations deterministically', () => {
  fc.assert(
    fc.asyncProperty(
      fc.array(fc.integer()),
      fc.shuffleArray,  // desordena el array de forma determinística
      async (items, shuffled) => {
        // Procesar en paralelo y verificar que el resultado es consistente
        const results = await Promise.all(
          items.map(i => processAsync(i))
        );
        const sorted = [...results].sort();
        expect(sorted).toEqual(sorted);  // siempre ordenable
      },
    ),
  );
});

Configuración avanzada

// Ejecutar 1000 pruebas en vez de las 100 por defecto
fc.assert(property, { numRuns: 1000 });

// Semilla reproducible para debugging
fc.assert(property, { seed: 12345 });

// Valores personalizados además de generados
fc.assert(property, {
  customReporter: {
    onRunComplete: (completion) => {
      console.log(`Tests: ${completion.counterexampleCount === null ? 'passed' : 'failed'}`);
    },
  },
});

// Verbose mode para debugging
fc.assert(property, { verbose: true });

Cuándo usar

• ✅ Validar invariantes matemáticas (orden, simetría, invertibilidad)
• ✅ Probar funciones de transformación/pure functions
• ✅ Generar edge cases que un humano no pensaría
• ✅ Testing de APIs REST (fuzzing de inputs)
• ✅ Detectar race conditions en código asíncrono
• ✅ Validar parsers y validadores de datos

Cuándo NO usar

• ❌ Testing de UI interactiva (mejor con Cypress/Playwright)
• ❌ Testing de integración de base de datos (mejor con fixtures)
• ❌ Cuando necesitas ejemplos específicos documentales (keep unit tests para eso)
• ❌ Propiedades que dependen de estado externo no determinista

Pitfalls

• ❌ No usar fc.pre() en exceso — si filtras el 90% de los inputs, fast-check es lento
• ❌ No mezclar expect() con return — en fast-check puro usa return boolean, en Jest usa expect() dentro de fc.context()
• ❌ Olvidar el shrinking — si un test falla, fast-check busca el contraejemplo mínimo. Si tu propiedad es compleja, el shrinking puede ser lento
• ❌ No fijar seed en CI — la seed aleatoria es buena para CI (detecta más bugs). Solo fija seed para debugging local
• ❌ No usar fc.string() para URLs/emails — usar fc.webUrl(), fc.asciiStringWithRandomCharacter() con filtro, o arbitraries específicos

Referencias

• Docs oficiales: https://fast-check.dev/
• Tutorial introductorio: https://fast-check.dev/docs/tutorials/quick-start/
• Arbitraries built-in: https://fast-check.dev/docs/core-blocks/arbitraries/
• Model-based testing: https://fast-check.dev/docs/advanced/model-based-testing/
• Race conditions: https://fast-check.dev/docs/advanced/race-conditions/
• Repo: https://github.com/dubzzz/fast-check (5k+ ⭐, MIT)

Skills relacionadas

• testing-jest-mocks-api — mocking de APIs externas con Jest
• systematic-debugging — metodología de 4 fases para debugging