# Migration guide

> [🇬🇧 English](./MIGRATION.md) • [🇯🇵 日本語](./MIGRATION.ja.md)

## 🎨 Rebrand notice (2026-06): dapp-e2e → kiwa

This project was rebranded from `dapp-e2e` to **`kiwa`** (際).
"際" (kiwa) means edge / boundary / limit, embodying the essence of boundary-value testing.
If you are coming from the old name, you can migrate using the mapping table below.

### Old → New mapping

| Category | Old | New |
|---|---|---|
| npm package (fixture) | `@dapp-e2e/core` | `@kiwa-test/dapp` |
| npm package (CLI) | `@dapp-e2e/cli` | `@kiwa-test/cli` |
| CLI bin | `dapp-e2e` | `kiwa` |
| init command | `pnpm dlx @dapp-e2e/cli init` | `pnpm dlx @kiwa-test/cli init` |
| import fixture | `import { dappE2eTest } from '@dapp-e2e/core'` | `import { dappE2eTest } from '@kiwa-test/dapp'` (function name is unchanged) |
| GitHub repo | `cardene777/dapp-e2e` | `cardene777/kiwa` (old URLs redirect automatically) |
| Claude Code skill name | `test-design` / `contract-test-foundry` / `contract-test-hardhat` / `dapp-e2e-test` | `kiwa-design` / `kiwa-forge` / `kiwa-hardhat` / `kiwa-play` |

### Mechanical replacement steps

```bash
# Bulk-replace dependencies in package.json
sed -i.bak 's|@dapp-e2e/|@kiwa-test/|g' package.json && rm package.json.bak
pnpm install
```

The same applies to import statements and CLI invocations: simply replace `@dapp-e2e/` with `@kiwa-test/`.
The API signatures, including the function name `dappE2eTest`, option keys, and event names, are **completely unchanged**. Only the namespace prefix changes.

### npm publish status

- `@dapp-e2e/*` remains **unpublished** on npm (`registry 404`), so no deprecation is needed
- `@kiwa-test/*` is published as `0.1.0` (changesets + GitHub Actions provenance, 2026-06-10, https://www.npmjs.com/package/@kiwa-test/dapp / https://www.npmjs.com/package/@kiwa-test/cli)

### Automatic redirect for GitHub URLs

URLs under `https://github.com/cardene777/dapp-e2e/*` are automatically redirected by GitHub to `https://github.com/cardene777/kiwa/*`. Existing PR / Issue numbers (`#1` through `#186`) remain valid on the new URLs as-is.

---

## Version compatibility guide

This document is for users who want to check compatibility differences when upgrading kiwa versions.
The v0.x line is still in the phase of refining the public API, so breaking changes may be introduced even in minor releases.
To make the impact of each release easy to review, this file serves as the migration entry point.

## Version policy

In v0.x, we prioritize converging the API over strict semver.
For that reason, changes that affect compatibility should go into minor releases rather than patches,
and the expected workflow is to update the README and related docs in the same PR.
Starting with v1.0.0, we will switch to strict semver, and breaking changes will be handled only in major releases.

### When to update this file

- when the API shape of `@kiwa-test/dapp` changes
- when the scaffold generated by the CLI changes
- when the Quickstart procedure changes
- when existing test code needs to be rewritten

## v0.0.x → v0.1.0

v0.1.0 is the first public release of kiwa.
As a result, there is effectively no migration work for existing users.

- **New**: `@kiwa-test/dapp`
  Provides the Playwright fixture, injector script, anvil lifecycle, 9 RPC methods, and 4 events.
- **New**: `@kiwa-test/cli`
  Provides `init` and `doctor`, and can generate a minimal scaffold.
- **Workspace layout**: `packages/core` `packages/cli` `examples/basic-connect`
- **Dependency policy**: `viem` and `@playwright/test` are treated as peer / dev dependencies

There are no replacement steps for existing code.
If you are adopting it from now, start with the Quickstart in [README.md](../README.md).

## How to write future entries

When introducing a breaking change, add a new entry above this section.

```markdown
## v0.X.y → v0.Y.0

- Summarize what changed in 1-3 lines
- List the affected packages and APIs
- Add before / after code examples if needed
- Include links to the related PRs or release
```

### Writing guidelines

- start each entry by stating what breaks
- if there is an alternative API, place it in the same section
- prioritize differences that are not sufficiently covered by the README
- for changes that only need additive documentation, prefer COMPARISON or the RPC docs

## Related

- [README.md](../README.md)
- [RELEASING.md](./RELEASING.md)
- [GitHub Releases](https://github.com/cardene777/kiwa/releases)
- [Issue tracker](https://github.com/cardene777/kiwa/issues)