Skip to content

nWave-ai/nWave / nWave/skills/nw-tdd-cross-language

nw-tdd-cross-language

Verified

Port the state-delta + property-based testing paradigm to languages other than Python. DIY recipes per language; canonical Python ref shipped in nwave_ai.state_delta.

Cross-Language State-Delta Porting Guide

This optional implementation guide is not a requirement to port an nWave API. Native discovery and applicability live in nw-test-design-mandates; its layered-mechanics module owns observation laws. Use incumbent native assertions, generators, shrinking/replay and helpers first. Matching nw-pbt-* guidance loads on need; unlisted languages use their real native tooling, not an EVIDENCE_GAP merely because no adapter is shipped. Never borrow Python as a substitute. The recipes below illustrate one optional helper implementation.

Unlisted languages (C, C++, OCaml, etc.) use their own native test, generator, shrinker and replay libraries; no Python-derived shim is imposed.


Canonical Python reference

Illustrative Python API contract (semantics reference only; not a required API, file path or predicate count; see nwave_ai.state_delta.matcher):

def assert_state_delta(
    before: Mapping[str, Any],
    after: Mapping[str, Any],
    universe: set[str],
    expected: Mapping[str, Predicate],
    *,
    strict: bool = False,
) -> None: ...

Predicate = Callable[[Any, Any], bool]

# Illustrative predicate factories (not a required set or count):
def prepended_with(prefix: str, sep: str = ":") -> Predicate: ...
def appended_with(suffix: str, sep: str = ":") -> Predicate: ...
def unchanged() -> Predicate: ...
def set_to(value: Any) -> Predicate: ...
def containing(substring: str) -> Predicate: ...
def normalized_to(normalizer: Callable[[Any], Any]) -> Predicate: ...
def idempotent_after(prefix: str, sep: str = ":") -> Predicate: ...
def legacy_healed(detector: Callable[[Any], bool], healed_check: Callable[[Any], bool]) -> Predicate: ...

Semantics:

  • For each key in universe:
    • If in expected: predicate must return True
    • If NOT in expected: implicit-unchanged (before[k] == after[k])
  • strict=True: keys in (before|after) - universe raise kind=strict_universe_mismatch
  • Multi-violation: ALL violations collected, ONE AssertionError raised

Porting recipe (conditional, language-agnostic)

Only when an existing native assertion/helper cannot express a needed public-state preservation observation, consider a small project-idiomatic helper. Translate the semantics needed by actual consumers, not a mandatory eight-predicate API or fixed path. Do not create a shim or additional allocations merely to match this illustrative Python reference.

Step 1 — Translate the semantics, only if a helper is needed

Adapt the function signatures using language-idiomatic types:

  • Universe = set/list of strings (Set<String>, string[], &[String], etc.)
  • Expected = map of string → predicate (Map<String, Predicate>, {[key: string]: Predicate}, HashMap<String, Box<dyn Fn>>)
  • Predicate = callable taking (old, new) → bool

Step 2 — Multi-violation collector (illustrative)

function assert_state_delta(before, after, universe, expected, strict=false):
    violations = []
    for key in universe:
        if key in expected:
            predicate = expected[key]
            if not predicate(before[key], after[key]):
                violations.append(predicate_failed_violation(key, before[key], after[key]))
        else:
            if before[key] != after[key]:
                violations.append(undeclared_change_violation(key, before[key], after[key]))
    if strict:
        for key in (before.keys ∪ after.keys) - universe:
            violations.append(strict_universe_mismatch_violation(key, before.get(key), after.get(key)))
    if violations:
        raise AssertionError(format_multiline_message(violations))

Step 3 — Predicates (only those consumers need)

Include only the predicates actual tests need; the Python eight are illustrative, not a required count. If added, each closes over its parameters using the language's idiom (illustrative: TypeScript arrow functions, Rust move closures, F# partial application, Java lambdas, Go returned funcs).

Step 4 — Compose with the native PBT library (if any)

If the project already has a generator/shrinker/replay library, it generates inputs and the native assertion or helper validates post-action state. Illustrative sketch:

property "installer preserves user PATH":
    forall(path: gen_realistic_path):
        before = capture_state()
        installer.install(path)
        after = capture_state()
        assert_state_delta(before, after,
                          universe={"PATH", "permissions", "hooks"},
                          expected={"PATH": prepended_with(app_bin)},
                          strict=true)

Illustrative mini-examples per language (not required APIs, paths or LOC)

TypeScript / fast-check

import { fc } from 'fast-check';
import { assertStateDelta, prependedWith } from './state-delta';  // hypothetical helper

fc.assert(
  fc.property(pathStrategy(), (userPath) => {
    const before = captureState();
    installShims(userPath);
    const after = captureState();
    assertStateDelta(before, after, {
      universe: ['PATH', 'permissions', 'hooks'],
      expected: { PATH: prependedWith('/app/bin') },
      strict: true,
    });
  })
);

Rust / proptest

use proptest::prelude::*;
use crate::state_delta::{assert_state_delta, prepended_with};  // hypothetical helper

proptest! {
    #[test]
    fn installer_preserves_user_path(user_path in path_strategy()) {
        let before = capture_state();
        install_shims(&user_path);
        let after = capture_state();
        assert_state_delta(
            &before, &after,
            &["PATH", "permissions", "hooks"],
            &[("PATH", prepended_with("/app/bin"))],
            true,  // strict
        ).unwrap();
    }
}

F# / FsCheck

open FsCheck.Xunit
open StateDelta  // hypothetical helper

[<Property>]
let ``installer preserves user PATH`` (userPath: PathShape) =
    let before = captureState()
    installShims userPath
    let after = captureState()
    assertStateDelta before after
        [ "PATH"; "permissions"; "hooks" ]
        [ "PATH", prependedWith "/app/bin" ]
        StrictMode.Strict

Java / jqwik

import net.jqwik.api.*;
import org.example.statedelta.StateDelta;  // hypothetical helper

class InstallerProperties {
    @Property
    void installerPreservesUserPath(@ForAll("paths") String userPath) {
        var before = captureState();
        installer.install(userPath);
        var after = captureState();
        StateDelta.assertStateDelta(
            before, after,
            Set.of("PATH", "permissions", "hooks"),
            Map.of("PATH", StateDelta.prependedWith("/app/bin")),
            true  // strict
        );
    }
}

When to NOT port (use canonical Python via subprocess)

If the SUT (system under test) is a Python service or CLI:

  • Skip language port; call Python from your language's test runner
  • Spawn the Python service, use Python assert_state_delta directly via test fixture
  • Cheaper than re-porting the matcher

If the SUT is in your language, first use the incumbent native assertions. Only if a public-state preservation observation cannot be expressed, add a minimal project-idiomatic helper with just the predicates consumers actually need; do not port a fixed predicate set.


Stage cascade applies cross-language

The 3-stage cascade in nw-tdd-methodology::Paradigm Mandate applies regardless of language:

  • Stage 0 (new code, paradigm-from-day-zero): debt never accumulates. Apply paradigm in whatever language as you write tests
  • Stage 1 (legacy bug-prone): state-delta migration captures debt (33-75% yield)
  • Stage 2a (post Stage 1): PBT amplification ~0% by design
  • Stage 2b (legacy bug-prone, no Stage 1): PBT amplification ~75%

Stage applicability is independent of language. The language-independent law: observe port-exposed state before and after the action, and fail closed on any unexpected change. Express it with the project's own native tooling; any helper is optional infrastructure.


Enterprise option

If your organization needs:

  • Tested, supported language packages (cross-version stability)
  • Cross-language consistency checks (same paradigm everywhere, audited)
  • Migration tooling (AI-assisted Stage 1 conversions in your language)

These ship as part of the nwave-pro enterprise bundle (deferred — contact the nWave team). Open-source path is sufficient for paradigm validation; enterprise reduces porting effort + adds support.


Quick reference

TaskResource
Read paradigm mandatenw-tdd-methodology::Paradigm Mandate
Read stage cascadenw-tdd-methodology::Empirical efficacy framework
Python canonical implementationnwave_ai.state_delta (matcher.py + predicates.py)
Python pilot exampletests/state_delta/integration/test_pilot_bug48.py (D-12 Part A + B)
Design directive (architects)nw-design::Development Paradigm Selection

For language-specific PBT library docs, see official:

  • fast-check: https://fast-check.dev/
  • proptest: https://docs.rs/proptest/
  • jqwik: https://jqwik.net/
  • FsCheck: https://fscheck.github.io/FsCheck/
  • gopter: https://github.com/leanovate/gopter
  • ScalaCheck: https://scalacheck.org/
  • qcheck: https://github.com/c-cube/qcheck
  • kotest (built-in): https://kotest.io/docs/proptest/property-based-testing.html
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall