property-based-testing

Property-Based Testing

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a (test-engineer, security-reviewer, api-contract-guardian) delege.

Felsefe

• Invariant > example. Generator yazdığında binlerce örnek otomatik.
• Shrinking olmadan PBT yok. Counter-example küçük + tek başına okunabilir.
• Generator = spec. Gevşek generator gevşek özellik kazandırır.
• Regression seed kalıcı. Bulunan counter-example commit'lenir.
• Property zayıfsa fuzzing yapıyorsun. "Exception fırlatmasın" özellik değil.
• PBT example-based test'i tamamlar, değiştirmez.

Ne Zaman Kullanılır

• Round-trip code (encode/decode, parse/serialize, JSON, protobuf, datetime, money, unicode)
• Algoritma (sort, search, hash, geometric, distributed)
• State machine (cart, payment intent, queue, cache)
• Schema-conformance API (OpenAPI varsa Schemathesis)
• Parser/protokol (HTTP, CSV, log line, URL)
• Edge case finding (unicode normalisation, timezone math, overflow)
• Flaky test fix → seed corpus oluştur, deterministic replay
• Regression coverage genişletme (mevcut example-based + PBT'yi ekle)

Tooling Matrisi

Dil / Katman	Tool	Stable mi?	Stateful var mı?	Notlar
Python	Hypothesis	Olgun	✅ RuleBasedStateMachine	pytest-hypothesis plugin; ghostwriter
TypeScript / JS	fast-check	Olgun	✅ fc.commands	@fast-check/jest, @fast-check/vitest
Go	gopter + native testing/fuzz (1.18+)	Orta	gopter ✅	gopter generic; native fuzz daha yeni
API (OpenAPI 3.x)	Schemathesis	Olgun	✅ link-following stateful	spec-driven, CI ready

Workflow

1) Discovery — kod tabanı PBT fırsatları

# Mevcut test kütüphaneleri
grep -rE "import hypothesis|from hypothesis" --include="*.py" | head
grep -rE "@fast-check|fast-check" --include="*.ts" --include="*.tsx" | head
grep -rE "gopter" --include="*.go" | head
grep -rE "schemathesis" --include="*.py" --include="*.yml" | head

# PBT'ye uygun fonksiyon adayı:
# - encode/decode, parse/serialize çiftleri
# - sort/normalize/merge gibi pure fonksiyonlar
# - state machine'ler (cart, queue, state pattern)
grep -rE "def (encode|decode|parse|serialize|normalize|merge)" --include="*.py"

2) Property hiyerarşisini uygula

Aday fonksiyon için 5 katmanlı property arama:

1. Invariant — değişmeyen tanım (length ≥ 0, non-negative).
2. Round-trip — decode(encode(x)) == x.
3. Idempotency — f(f(x)) == f(x) (sort, normalize, dedupe).
4. Oracle — basit referans impl ile kıyas.
5. Metamorphic — input X transform → output Y transform.

Hangisi mümkün? Çoğu fonksiyon için 1-3 katmandan en az birisi geçerlidir.

3) Generator yaz

Python (Hypothesis):

from hypothesis import given, strategies as st, settings, HealthCheck

@given(st.text(min_size=1, max_size=200))
@settings(max_examples=500, deadline=2000)
def test_encode_decode_round_trip(s: str) -> None:
    assert decode(encode(s)) == s

TypeScript (fast-check):

import fc from 'fast-check';

test('encode/decode round-trip', () => {
  fc.assert(
    fc.property(fc.string({ minLength: 1, maxLength: 200 }), (s) => {
      expect(decode(encode(s))).toBe(s);
    }),
    { numRuns: 500, seed: 42 },
  );
});

Go (gopter):

func TestEncodeDecodeRoundTrip(t *testing.T) {
    properties := gopter.NewProperties(nil)
    properties.Property("round-trip", prop.ForAll(
        func(s string) bool { return decode(encode(s)) == s },
        gen.AlphaString().WithLabel("s"),
    ))
    properties.TestingRun(t)
}

Composition (Python @composite):

@st.composite
def order_lines(draw):
    sku = draw(st.text(min_size=3, max_size=10))
    qty = draw(st.integers(min_value=1, max_value=999))
    price_cents = draw(st.integers(min_value=1, max_value=10_000_000))
    return {"sku": sku, "qty": qty, "price_cents": price_cents}

4) Stateful PBT

Aggregate / cart / payment intent / cache gibi state-li domain için:

from hypothesis.stateful import RuleBasedStateMachine, rule, invariant

class CartStateMachine(RuleBasedStateMachine):
    def __init__(self):
        super().__init__()
        self.cart = Cart()

    @rule(line=order_lines())
    def add_line(self, line):
        self.cart.add(line)

    @rule()
    def checkout(self):
        if not self.cart.is_empty():
            self.cart.checkout()

    @invariant()
    def total_non_negative(self):
        assert self.cart.total() >= 0

State machine binlerce komut dizilimini deneyip invariant'ı her adımda kontrol eder; tek başına example'la bulunması olanaksız edge case'leri yakalar.

5) Schema-driven (Schemathesis) — OpenAPI varsa

# Lokal
schemathesis run \
  --checks all \
  --hypothesis-max-examples=200 \
  --hypothesis-deadline=2000 \
  https://api.acme.com/openapi.json

# CI gate (GitHub Actions)
schemathesis run \
  --checks all,response_schema_conformance \
  --report-junit=schemathesis-report.xml \
  --stateful=links \
  openapi.yaml

Schemathesis bulgu örnekleri:

• 500 error — handler beklenmedik input türünde crash (eksik validation).
• 422 schema yanlış — spec parametre tanımı koda uymuyor.
• content-type confuse — application/json ile XML kabul ediyor.
• header injection — \r\n smuggling.

6) Regression seed corpus

Counter-example bulunduğunda kalıcılaştır:

# Hypothesis: .hypothesis/examples/ dir auto-managed (sqlite). Commit'le.
# .gitignore'a `.hypothesis/examples/` EKLEME — KALICI corpus.

# Manual seed:
@given(st.text())
@example("\x00")          # bulunan counter-example
@example("café")          # unicode normalisation bug
def test_normalize(s: str) -> None:
    assert normalize(normalize(s)) == normalize(s)

fast-check:

// seed manuel ekleme
fc.assert(
  fc.property(fc.string(), (s) => normalize(normalize(s)) === normalize(s)),
  {
    seed: 1234567,    // failed run seed (kalıcı kayıt)
    path: '0:0:1',    // shrink path
    numRuns: 0,       // sadece seed/path replay
  },
);

7) CI gate

# .github/workflows/test.yml
- name: PBT (Hypothesis)
  run: pytest --hypothesis-profile=ci -q
  env:
    HYPOTHESIS_PROFILE: ci

# Hypothesis profile (conftest.py)
# settings.register_profile("ci",
#   max_examples=500, deadline=2000,
#   suppress_health_check=[HealthCheck.too_slow],
#   derandomize=False, print_blob=True)

- name: Schemathesis (API)
  run: |
    schemathesis run --checks all \
      --hypothesis-max-examples=100 \
      --report-junit=stx.xml \
      openapi.yaml

8) Bulgu Raporu

# PBT Findings: <module/path>

## Critical
- [ ] decode/encode round-trip `\x00` byte için fails — `parser.py:42` —
      counter-example: `b"\x00\x00"` shrink edilmiş

## High
- [ ] cart aggregate total negatif olabilir checkout retry sonrası —
      `cart.py:118` — state machine 14 komut sonrası invariant violation

## Medium
- [ ] schemathesis: POST /orders content-type missing → 500 (422 olmalı) —
      `routes/orders.py:23` — issue #ABC-123

## Low
- [ ] generator `text(min_size=0)` boş string filter rate %12 — health check
      warning

Checklist

• Property'nin "hangi hiyerarşi" katmanından geldiği belirlendi mi (invariant / round-trip / idempotency / oracle / metamorphic)?
• Property "exception fırlatmasın"dan daha güçlü mü?
• Generator domain'i fonksiyon spec'i kadar geniş mi, daha mı dar?
• Shrinking çalışıyor mu (counter-example küçük + okunabilir)?
• Regression seed corpus commit'lendi mi?
• CI profile (deadline + max_examples + deterministic) tanımlı mı?
• Stateful PBT state-li domain için kullanıldı mı (varsa)?
• Schemathesis OpenAPI spec varsa CI gate'de mi?
• assume() filter rate < %30?
• Health check warning'leri var mı (Filtered too many, Slow data)?

Antipattern

• "Exception fırlatmasın" property → fuzzing yapıyorsun; gerçek invariant yaz.
• Generator domain'i 1-2 byte string → bug-finding yok; bug-confirming yapıyorsun.
• assume() filter ile invariant kurtarma → generator'ı düzelt.
• Shrinking devre dışı → counter-example okunamaz; PBT değer kaybeder.
• derandomize=True yapıp seed flat → flake bulamazsın; tersine PBT'nin amacı stochastic exploration.
• Stateful PBT'de mutable global state → replay imkânsız.
• Hypothesis .hypothesis/examples/ .gitignore'da → regression corpus her CI run'da kaybolur.
• Schemathesis fail'leri "spec hatası" diye bastırma — spec yanlış veya impl yanlış; karar CI'da verilir, agent süpürmez.
• Counter-example'ı kod yorum olarak yapıştır ama @example'a eklememek.
• Test deadline yok → flake (slow generation veya slow impl).
• PBT yerine fuzzing tools (atheris, libFuzzer) kullanmak — PBT generator- driven invariant; fuzzing coverage-guided runtime exploration. İkisi farklı araç.

Cross-Link

• rules/property-based-testing.md — discipline rule.
• rules/testing.md — piramit içinde PBT konumu (unit + integration arası).
• skills/qa-strategy/SKILL.md — quality gate matrisinde PBT katmanı.
• agents/test-engineer.md — PBT planlama + flake yönetimi sahiplik.
• agents/api-contract-guardian.md — Schemathesis bulgusu spec değişikliği tetiklediğinde.
• commands/property-test-review.md — slash command entrypoint.