kiwa

際を制するものが 開発を制する。 The dev-flow platform where testing, formal verification, and spec-driven development meet.

kiwa (「際」 = boundary, edge, connection) is a spec-driven development platform that fuses 3 axes: runtime testing (40+ npm packages), formal verification (Lean 4 spec generator + lean --check), and spec-driven workflow (specFormal / specRuntime 2-file separation with 3-layer classification). Read the MANIFESTO for the full philosophy.

Every test layer · one spec · every verification path · TypeScript / Solidity / Python / Lean 4.

One Layer 1 spec → contract / API / component / e2e / a11y / visual / Next.js (Server Actions / middleware / RSC) tests in parallel, across 42+ npm packages + 1 PyPI package + Foundry / Hardhat bridges + Lean 4 spec verification. Coverage and Mutation gates enforced at release by scripts/check-{coverage,mutation}-gates.mjs.

Quickstart • 4 layer chain • Features • Examples • Docs • Cookbook • FAQ • Changelog • License

Status: pre-release. kiwa is public for visibility only. Source is under an "All rights reserved" license until general availability; see LICENSE for what you may and may not do. Issues and pull requests are conducted in English per CONTRIBUTING.md.

🇬🇧 English • 🇯🇵 日本語

_{▶ Watch the full-quality MP4 (2.9 MB, 1920×1080, h264)}

🎨 Rebrand notice: This project was renamed from dapp-e2e to kiwa (際) in 2026-06. dapp-e2e was a Playwright-only E2E fixture; kiwa is the same fixture plus Layer 1 test design + Layer 2 contract test generators (Foundry / Hardhat). The Playwright fixture API itself is unchanged — see docs/MIGRATION.md § Rebrand notice for the package-name mapping.

Modern stacks scatter their tests across mismatched runners: Foundry / Hardhat for contracts, Vitest for unit + API, Playwright for e2e, Testing Library for components, axe-core for a11y, pixelmatch for visual, pytest for Python services. Every runner has its own conventions, fixtures, and gates — and no single source of truth spans them.

kiwa is a test toolchain that turns one Layer 1 spec into every test layer your stack actually needs. "kiwa" means edge / boundary / limit in Japanese — exactly what good tests prove. dApps and smart contracts are first-class citizens, alongside REST APIs (msw / supertest / Playwright request), SPA components (8 framework adapters), CLI tools, queue workers, generic browser e2e (Playwright), accessibility (axe-core), visual regression (pixelmatch), Next.js App Router (Server Actions / middleware / RSC), and Python pytest (port of the spec parser + requests/httpx adapter, published as kiwa-test-py on PyPI).

graph TD
    A[Your code: TS / Python / Solidity] --> B["/kiwa-design Layer 1"]
    B --> C[9-column spec — single source of truth]
    C --> D["/kiwa-forge → Foundry .t.sol"]
    C --> E["/kiwa-hardhat → Hardhat .test.cjs"]
    C --> F["/kiwa-vitest → Vitest .test.ts"]
    C --> G["/kiwa-api → msw + supertest"]
    C --> H["/kiwa-play → Playwright .spec.ts"]
    C --> I["a11y + visual + CLI + data adapters"]
    D --> J[forge test]
    E --> K[npx hardhat test]
    F --> L[vitest run]
    G --> L
    H --> M[playwright test + 4-round flake check]
    I --> L
    J --> N[Coverage gate ≥ 90/80/90/90]
    K --> N
    L --> N
    M --> N
    N --> O[Mutation gate — per-package MSI ≥ 80%]
    O --> P[release publish]

Already have code? kiwa is designed retrofit-first: every Layer 2 generator can reverse-engineer a spec from existing tests. See tests/docs/retrofit-existing-dapp.md for a dApp walkthrough, @kiwa-lab/api / @kiwa-lab/ui / @kiwa-lab/cli-test for non-dApp stacks.

kiwa ships in two halves that work together but stand alone:

You can use the skills alone (no npm dependency — they just generate test files) or the fixture alone (no Claude — just pnpm add @kiwa-lab/dapp), or both together for the full chain.

Run the chain against examples/nextjs-token-gating — already contains GatedContent.sol + GateNFT.sol + existing Playwright tests.

# Step 1: Generate a contract-side spec from the existing .sol files
/kiwa-design --layer contract --module token-gating \
  --input examples/nextjs-token-gating/contracts/GatedContent.sol
# → .context/spec/contract/test-spec-token-gating.md (9 sections, 11 test cases across 6 viewpoints)

# Step 2: Generate Foundry tests from that spec
/kiwa-forge --module token-gating
# → test/GatedContent.t.sol (20 tests including fuzz)
# → forge test → 20/20 PASS
# → forge coverage → Lines 100% / Branches 87.50%  ✅ passes the gate

# Step 2': Generate Hardhat tests from the SAME spec (parallel)
/kiwa-hardhat --module token-gating
# → test/GatedContent.test.cjs (24 tests with fast-check)
# → npx hardhat test → 24/24 PASS
# → npx hardhat coverage → Branches 80.56%  ✅ passes the gate

# Step 3: Extend the existing Playwright tests using the same spec
# (run from examples/nextjs-token-gating/ — Step 0 auto-detects the dApp project)
/kiwa-play --mode extend
# → tests/gating.spec.ts adds missing viewpoints (no regression on 8 existing tests)
# → pnpm test x4 rounds → 4/4 PASS, 0 flake

Same TC-001 … TC-020 test IDs appear in both Foundry and Hardhat output — your team can pick a runner per developer without fragmenting the spec.

Every kiwa surface follows the same kiwa-design → Layer 2 generator → kiwa-review chain. The spec format (9 sections) and the 11 viewpoints catalog are shared across all surfaces, so once you learn the contract chain you already know the dApp E2E / generic E2E / a11y / visual / API / UI chains.

/kiwa-test --target {contract|dapp|web|both|all} orchestrates the chain end-to-end for any subset of surfaces — web runs the generic e2e / a11y / visual trio against the same app/ source, and all covers all 6 web-side surfaces (contract + dapp + web). The integrated report at tests/reports/integrated/{example}-{target}.{lang}.md aggregates every surface's pass/fail count, coverage, and reviewer score in one table.

Install the kiwa skill chain as a Claude Code plugin — no clone required, available across any of your dApp projects after install.

# In Claude Code (run from any project):
/plugin marketplace add cardene777/kiwa
/plugin install kiwa@kiwa-marketplace
/reload-plugins                            # activate without restarting the session

After install, all 30 skills appear under the kiwa: namespace (Claude Code namespaces plugin skills by plugin name). Inside any dApp project, run the individual layers:

# Layer 1 — design tests (output: tests/spec/<layer>/test-spec-<module>.md)
/kiwa:kiwa-design --layer contract --input path/to/YourContract.sol --module your-module
/kiwa:kiwa-design --layer unit --module your-module
/kiwa:kiwa-design --layer integration --module your-module

# Layer 2 — implement tests from the spec
/kiwa:kiwa-forge --module your-module          # Foundry contract tests
/kiwa:kiwa-hardhat --module your-module        # Hardhat contract tests (parallel runner option)
/kiwa:kiwa-vitest --module your-module         # Vitest unit (F-3)
/kiwa:kiwa-api --module your-module            # API integration (F-3)
/kiwa:kiwa-play --init                          # Bootstrap Playwright fixture for a fresh dApp
/kiwa:kiwa-play --mode new                      # Add new dApp e2e tests
/kiwa:kiwa-play --mode extend                   # Extend existing dApp e2e tests

# Review — covers spec / test / result (provide --module + --layer to resolve paths)
/kiwa:kiwa-review --mode test-review --module your-module --layer contract

The --example flag and /kiwa:kiwa-test one-shot orchestrator are intended for the kiwa monorepo itself (which has examples/). Plugin users run the individual skills above directly from their project.

Update the plugin later:

/plugin marketplace update kiwa-marketplace  # refresh the catalog
/plugin update kiwa@kiwa-marketplace         # apply the new version

# 1. Clone & install
git clone https://github.com/cardene777/kiwa.git && cd kiwa
pnpm install

# 2. In Claude Code (run from the kiwa repo), the project-local skills load automatically
/kiwa-test --example nextjs-token-gating   # one-shot orchestrator (kiwa repo only, uses examples/)

pnpm dlx @kiwa-lab/cli init
pnpm install
pnpm exec playwright test

Prerequisites: Node.js 20+ · pnpm/npm/yarn · Foundry (anvil + forge) · Playwright (pnpm exec playwright install)

init scaffolds:

e2e/
├── connect.spec.ts         ← Playwright spec wired to dappE2eTest
playwright.config.ts        ← Headless Chromium config
package.json                ← test:e2e script + peer deps

Now available on npm — pnpm dlx @kiwa-lab/cli init works out of the box (no clone required).

If you are hacking on kiwa itself and want to test changes against a local dApp project before publishing, link with a file: dependency:

# 1. Clone & build kiwa
git clone https://github.com/cardene777/kiwa.git ~/kiwa
cd ~/kiwa
pnpm install
pnpm -F @kiwa-lab/dapp -F @kiwa-lab/cli build

# 2. In your test project, add a file: dependency
cd /path/to/your-dapp
pnpm add -D file:$HOME/kiwa/packages/dapp file:$HOME/kiwa/packages/cli

# 3. Scaffold from the locally-installed CLI
pnpm exec kiwa init     # or: node $HOME/kiwa/packages/cli/dist/index.js init

For everyday use, prefer Option C (pnpm dlx @kiwa-lab/cli init) which pulls the published 0.1.0 version directly.

@kiwa-lab/dapp ships both ESM and CJS builds (dist/index.js + dist/index.cjs), so both import and require resolve correctly. You can drop it into any of:

If you still hit Error: No "exports" main defined (older toolchains), isolate the kiwa test dir as ESM with a local package.json:

mkdir -p tests/kiwa
echo '{"type":"module"}' > tests/kiwa/package.json

Only tests/kiwa/**.ts is treated as ESM; the rest of your tests/ keeps its existing CJS resolution.

@kiwa-lab/dapp aims to be production-realistic but explicit about deltas. Key default behavioural differences:

The full RPC fidelity matrix lives in docs/MOCK-DESIGN.md (A/B/C level scoring rubric).

• 📋 9-section unified spec — Target / Spec summary / Quality risks / Recommended composition / Viewpoints / Cases / Automated / Manual / Insufficient spec
• 🎯 10-viewpoint catalog — Happy / Failure / Boundary / State transition / Permission / Validation / Idempotency / Concurrency / Performance / Security
• ⚖️ 5-criteria risk scoring — Revenue / Security / Data destruction / Frequency / Past incidents → drives test priority deterministically
• 📄 9-column case table — Test ID / Level / Viewpoint / Precondition / Input / Steps / Expected / Priority / Automation
• 🔁 Retrofit-first — reverse-engineers specs from existing .sol, app/, tests/, OpenAPI specs

• 🔨 Foundry mapping — fuzz / invariant + Handler / vm.prank / vm.expectRevert(Error.selector) / vm.warp / --gas-report
• ⚒️ Hardhat mapping — chai-matchers revertedWithCustomError / fast-check asyncProperty / loadFixture / hardhat-gas-reporter
• 🪞 Mirror generation — both runners produce the same TC-NNN IDs from one spec; teams can run Foundry, Hardhat, or both
• 🛡️ Coverage gate enforced — Lines ≥ 90%, Statements ≥ 90%, Branches ≥ 80%, Funcs ≥ 90%. The skill won't write test-passed marker until all four metrics pass

• 🦊 Inject window.ethereum without any browser extension
• ⚡ Spawn anvil per test for total chain isolation
• 🔌 9 RPC methods handled directly (eth_requestAccounts / personal_sign / eth_signTypedData_v4 / eth_sendTransaction / wallet_switchEthereumChain …), the rest forwarded to anvil
• 📡 EIP-1193 events — accountsChanged / chainChanged / connect / disconnect triggerable from tests
• 👛 EIP-6963 multi-wallet — declare MetaMask, Rabby, Coinbase, … side-by-side
• 🤖 Smart contract account (AA) — isContractAccount: true reroutes personal_sign through EIP-1271, eth_sendTransaction through execute()
• 📦 viem as peer dep — your project owns the version
• 🔁 --mode extend — appends new viewpoints without breaking existing tests, 4-round flake check built in
• ❌ error envelope preserves code and message across page boundaries

kiwa sits at the intersection of two ecosystems. Short version:

See docs/COMPARISON.md for the full comparison tables (Synpress / dappwright / wallet-mock / kiwa on the fixture axis, plus hardhat-test-suite-generator / Foundry AI / Claude Code spec-driven dev on the test-generation axis), selection guide, and the explanation of why kiwa intentionally does not own MetaMask extension automation.

@kiwa-lab/* packages target Node.js 22+ as the production baseline. Bun (bun.sh) is also supported for the entire 19-package matrix — all packages pass Vitest under Bun without modification.

# install deps (still requires pnpm)
pnpm install

# run a single package's tests under Bun
cd packages/edge
bunx --bun vitest run

# loop over every package
for pkg in core api ui data cli-test observability e2e cli a11y visual nextjs nuxt sveltekit remix astro solidstart qwikcity edge; do
  (cd packages/$pkg && bunx --bun vitest run)
done

Vitest itself doesn't need a Bun-specific runner — Vitest's Node compat surface is exercised through Bun's Node API shim. bun test (Bun's native runner) is NOT used because Vitest's API surface (describe / it / vi.mock) is incompatible with Bun's native runner.

# install deps (still requires pnpm)
pnpm install

# run a single package's tests under Deno
cd packages/edge
deno run --allow-all npm:vitest run

# loop over every package
for pkg in core api ui data cli-test observability e2e cli a11y visual nextjs nuxt sveltekit remix astro solidstart qwikcity edge; do
  (cd packages/$pkg && deno run --allow-all npm:vitest run)
done

Deno reads Vitest through its npm: specifier compatibility layer — no deno.json import map required. --allow-all is the simplest permission set; real-world Deno consumers can tighten this to --allow-read --allow-env --allow-net=localhost for sandboxed CI.

/kiwa-forge and /kiwa-hardhat block the test-passed marker until all four coverage metrics clear thresholds. Default values (tuned for OSS-grade smart contracts):

If any metric falls short, the skill records the under-covered viewpoints / error paths / events back into the Layer 1 spec's "Insufficient spec" section so the next loop can address them — instead of silently signing off on weak tests.

Override with --coverage-lines 95 --coverage-branches 85 etc.

kiwa enforces two independent gates at release time so a publish can't ship without both. Both gates run via local /verify skill (pre-merge) and scripts/check-{coverage,mutation}-gates.mjs (pre-publish) and fail if any package regresses.

Lines / Statements / Functions ≥ 90 %, Branches ≥ 80 %, across all 11 packages. Optional-peer-dep error paths in the adapter wrappers (msw / pixelmatch / pngjs / @testing-library/* / @vue/test-utils / @solidjs/testing-library / lit / @noma.to/qwik-testing-library / @testing-library/angular) are why Branches stays at 80 — they cannot be exercised when their peer is installed for the package-local tests.

Stryker runs against the compiled .vitest-dist/src/ artefacts for every package and the gate computes MSI = killed / (killed + survived + timeout). Thresholds are intentionally per-package — pure-logic packages hold to 90 %+, thin wrappers around third-party libs are pinned at 80 %.

Run both gates locally:

pnpm test:mutation                  # builds + mutates all 11 packages
pnpm gate:mutation                  # asserts the per-package thresholds
pnpm gate:coverage                  # asserts Lines/Branches/Functions thresholds

For a reverse lookup by feature, jump to docs/en/examples/README.md. For a 30 min ~ 1 hour guided tour through five popular examples, follow docs/en/examples/walkthrough.md. Per-example READMEs live under examples/{name}/README.md (bilingual README.ja.md available for the popular five — basic-connect / mint-nft / defi-swap / nextjs-wagmi-rainbow / nft-marketplace).

These three examples have forge test + hardhat test (where applicable) + playwright test, all in 4-round zero-flake state, with coverage gates passed:

20 reference dApps live under examples/, proving the fixture against a wide stack:

@kiwa-lab/{framework} の helper を 実 framework dev server で動かす reference 実装。 Pattern A (Dependency Injection) で thin wrapper / pure logic を分離、 unit test (kiwa helper、 Nitro 不要) と e2e test (Playwright + 実 dev server) を 同じ pure logic に対して別 angle で走らせる構成。 OSS contributor が自プロジェクトに kiwa を導入する際の参考に。

import { dappE2eTest } from '@kiwa-lab/dapp';

const test = dappE2eTest.extend({
  wallets: [
    {
      name: 'MetaMask',
      rdns: 'io.metamask',
      icon: 'data:image/svg+xml;base64,...',
      privateKey: '0xac09...ff80',
    },
    {
      name: 'Rabby',
      rdns: 'io.rabby',
      icon: 'data:image/svg+xml;base64,...',
      privateKey: '0x59c6...690d',
    },
  ],
});

test('multi wallet picker', async ({ page, dappE2e }) => {
  await dappE2e.wallets!['io.rabby'].connect();
});

When wallets is unset, a single MetaMask-compatible wallet runs (backward compatible).

Phase E rebrand snapshot (main @ b7267a7):

The 4-round flake check is mandatory before any release tag — runner at .context/scratch/multi-round-all-examples.sh (developer-side).

Adversarial review patterns are catalogued in adversarial-pitfalls.md as a self-check checklist for false positives.

Full 5-section docs (Quickstart / Concepts / API / Cookbook / FAQ) maintained in JP↔EN 1:1 translation under docs/.

• 🇬🇧 English documentation
• 🇯🇵 日本語ドキュメント

Reference docs:

For Claude Code users — full skill reference:

• /kiwa-design — Layer 1 spec generator
• /kiwa-forge — Foundry generator
• /kiwa-hardhat — Hardhat generator
• /kiwa-play — Playwright generator + 22-example index + 9 false-positive patterns

kiwa v1.0 ships complete coverage for the layers below. The table is exhaustive and intentionally honest — features outside this list are tracked in Roadmap below, not silently missing.

Next.js, Nuxt, SvelteKit, Remix, and Astro client-side pages are tested through /kiwa-ui (React / Vue / Svelte component layer) plus /kiwa-e2e (browser layer). Next.js API Routes under app/api/*/route.ts are tested through /kiwa-api (examples/nextjs-api-poc/ is a working reference).

If your stack falls outside the ✅ list above, kiwa is still useful for the layers it does cover (e.g., your Next.js client + API routes still work even if Server Actions need hand-writing for now), but don't expect the chain to cover everything end-to-end. The Roadmap below shows where coverage is heading.

Contributions welcome — pick an issue from the milestone label list above and follow CONTRIBUTING.md.

• 📖 Read CONTRIBUTING.md — dev setup + skill chain workflow + PR checklist
• 🤝 Code of Conduct — Contributor Covenant 2.1
• 🔒 Security policy — Report vulnerabilities privately
• 🐛 Open an issue
• 🔀 Send a pull request
• 🗺️ Open Issues (current roadmap): enhancement label
• 💡 Check docs/MIGRATION.md before reporting breaking-change concerns

• 💬 GitHub Discussions — Long-form questions, proposals, Show & Tell. Start with the v0.5 announcement for what landed in the latest cut.
• 🐦 X / Twitter @cardene777 — Quick replies and DMs. Release threads land here too.
• 📰 Zenn @cardene777 — Long-form articles and write-ups (v0.5 deep-dive linked from the README badge).

For bug reports, please open an Issue so the discussion stays searchable. For private security disclosures, use the Security advisory channel (see SECURITY.md).

MIT © cardene — find me on GitHub and X.