SeleniumPlaywrightMigrator 0.0.3-preview.1

SeleniumPlaywrightMigrator

Execution model: one standard full-project run is supported. pilot is optional calibration; partition-specific planning and acceptance state are not used.

Dotnet tool for agent-assisted and human-reviewed migration of Selenium tests toward Playwright.

The stable public path is Selenium C# to Playwright .NET with NUnit as the default target framework and xUnit as a supported target framework. Playwright TypeScript, Java Selenium, and Python Selenium paths are available as experimental preview capabilities; check the repository documentation before using them for production migrations.

Install/update sanity check

After installing through npm, standalone, or dotnet tool, run:

selenium-pw-migrator doctor install
selenium-pw-migrator self update --print-command

doctor install prints the resolved executable, version, channel, PATH candidates, runtime, and recommended update command. For the npm wrapper, the normal update command is:

npm update -g selenium-pw-migrator

Product-repo onboarding

selenium-pw-migrator start --input ./OldTests --agent opencode --workspace migration
selenium-pw-migrator pilot --input ./OldTests --max-tests 10 --out migration/pilot

start writes a profile skeleton, current-ticket.md, and a no-menu dispatch state for /supervised-task. pilot chooses a representative small slice, copies it to selected-input/, and points next commands at that bounded input before the first full migration batch.

Basic usage

# Local tool manifest
dotnet tool run selenium-pw-migrator -- --help
dotnet tool run selenium-pw-migrator -- --mode doctor --input ./OldTests --config ./profiles/base.adapter.json --out doctor
dotnet tool run selenium-pw-migrator -- --mode runbook --input ./OldTests --config ./profiles/base.adapter.json --out runbook --format both
dotnet tool run selenium-pw-migrator -- --mode migrate --input ./OldTests --config ./profiles/base.adapter.json --target-test-framework xunit --out generated-tests --format both
dotnet tool run selenium-pw-migrator -- --mode capabilities --out capabilities --format both

Relative --out values are written under the default migration/ workspace.

Cross-platform migration kit

dotnet tool run selenium-pw-migrator -- kit init --workspace migration --source ./OldTests
dotnet tool run selenium-pw-migrator -- kit update --workspace migration --backup
dotnet tool run selenium-pw-migrator -- kit doctor --workspace migration
dotnet tool run selenium-pw-migrator -- kit next-ticket --workspace migration

CLI help

dotnet tool run selenium-pw-migrator -- --help
dotnet tool run selenium-pw-migrator -- --mode migrate --help
dotnet tool run selenium-pw-migrator -- --mode verify-project --help

Use selenium-pw-migrator --help only after a global install.

Commands are grouped as stable public, experimental preview, and internal/maintainer. The command catalog is documented in docs/cli-productization.md in the repository.

Useful modes

• kit init/update/doctor/next-ticket — install, update, check, and continue the migration workspace.
• kit bootstrap-opencode / kit bootstrap-agent --agent codex|generic — create an agent-ready workspace for OpenCode or a non-OpenCode handoff pack.
• runbook — generate pilot scope, command chain, risk map, artifacts, and acceptance checklist before the first migration run.
• start — product-repo onboarding wizard that writes a profile skeleton and next command chain.
• pilot — select a representative bounded migration slice before scaling.
• run — execute the complete configured source through the standard full-project pipeline.
• doctor install / install-doctor — explain the active install channel and update command.
• doctor — preflight input, config, tooling, and source-truth hints.
• analyze — inspect Selenium tests without generating target files.
• migrate — generate Playwright target files.
• verify / verify-project — check generated output and compile generated Playwright .NET tests.
• verify-ts-project — experimental TypeScript project-aware type-checking.
• index-pom — extract Selenium POM selector evidence plus target-side Playwright/Kontur POM facts.
• helper-inventory — scan Selenium helper/POM method bodies and infer MethodSemantics candidates.
• explain-todo, smoke-plan, runtime-classify, selector-evidence, migration-board, report-serve — prioritize follow-up work from migration artifacts/runtime logs, classify runtime root causes, write suggested-config-patch.md/json, score readiness, explain selector provenance, and export triage decisions.
• pr-pack — create a PR/review bundle with before/after metrics, changed/generated files list, risk summary, reviewer checklist, evidence references, and suggested PR description.
• config-validate, config-diff, guard — keep human and agent changes safe.
• capabilities — list built-in source frontend and target backend support matrices.

Source-truth rule

Do not invent selectors. Use Selenium PageObject code, verified HTML attributes, existing Playwright tests/POMs, or reviewed helper semantics. If source truth cannot be proven, preserve an explicit TODO.

Repository docs

• docs/quick-start.md
• docs/migration-runbook.md
• docs/examples/end-to-end-simple.md
• docs/articles/ast-migration-explained.md
• docs/articles/ast-migration-explained.ru.md
• docs/user-guide/README.md
• docs/config-profile-guide.md
• docs/user-guide/limitations.md
• docs/troubleshooting.md
• docs/packaging-and-distribution.md
• docs/tool-installation.md
• docs/cli-productization.md
• docs/extensibility.md
• docs/public-roadmap.md

Agent contract pack

Generate a ticket-specific prompt and safety pack for agent loops:

selenium-pw-migrator agent contract --input migration/current-ticket.md --config ./adapter-config.json --out migration/agent-contract --format both

The command writes agent-contract.md/json, allowed paths, stop policy, exact commands, report template, and role prompts under agent-prompts/ for specialized contract-pack workflows.

Migration PR pack

selenium-pw-migrator pr pack --input migration/runs/latest --config ./adapter-config.json --out migration/pr-pack --format both

Writes pr-summary.md, pr-pack.json, reviewer-checklist.md, and suggested-pr-description.md.

• config author / --mode config-author — propose small evidence-driven config changes and config-diff commands without applying them.
• learn pack / --mode learn-pack — extract reusable migration knowledge into a learning pack and reviewable profile layer.

Generation Policy

Use --generation-policy conservative|balanced|aggressive to control mapped-helper generation risk. Conservative produces more review/TODO output, balanced keeps current behavior, and aggressive emits more explicit mapped helper code with report risk annotations. See docs/generation-policy.md.

Framework matrix report

Generate a project-specific framework matrix and source framework detection report:

selenium-pw-migrator framework matrix --input ./OldTests --target dotnet --target-test-framework xunit --out framework-matrix --format both

This writes framework-matrix.md/json and source-framework-detection.md/json. It is read-only, flags MSTest as detected/unsupported, and keeps Java/Python target frameworks marked as planned until implemented.

Five-minute playground

selenium-pw-migrator playground --out playground --target-test-framework xunit --generation-policy conservative
selenium-pw-migrator playground verify --input playground --out playground-verify
cat playground/try-this-first.md

The playground creates a disposable public demo workspace with ready commands, expected outputs, dashboard sample, and PR pack sample. It is read-only with respect to real projects.

Release readiness

Before publishing a NuGet preview from the source repository, run:

selenium-pw-migrator doctor release --out release-doctor --format both

The release doctor checks PackageId/version metadata, README_TOOL packaging docs, release scripts, publish workflow dry-run support, NuGet/npm/standalone smoke coverage, install diagnostics, agent handoff UX, changelog consistency, and basic repository hygiene.

Standard full-project run

Install or update the OpenCode project command pack once:

selenium-pw-migrator kit bootstrap-opencode --workspace migration --source ./OldTests --opencode-install auto

Then use /supervised-task, or execute the same pipeline manually:

selenium-pw-migrator pilot --input ./OldTests --max-tests 10 --out migration/pilot
selenium-pw-migrator run --input ./OldTests --config migration/profiles/adapter-config.json --out migration/runs/run-001 --format both
selenium-pw-migrator --mode verify-project --input ./OldTests --config migration/profiles/adapter-config.json --out migration/runs/run-001/verify-project --format both

run is the only full migration entry point. It performs analyze, generate, verify, and mapping-proposal stages in one ordinary directory. The configured source remains the hard boundary. Missing target tooling or a CLI failure must be reported; never create replacement verification JSON manually.

Config delta merge

selenium-pw-migrator config merge-deltas --base migration/adapter-config.json --deltas migration/state/memory/config-deltas --out migration/config-merge
selenium-pw-migrator config validate-merge --base migration/adapter-config.json --candidate migration/config-merge/adapter-config.merged.json --out migration/config-merge

config merge-deltas creates a candidate adapter-config.merged.json plus merge-report.md/json and conflicts.jsonl. config validate-merge writes validate-merge-report.md/json and checks duplicate/conflicting stable keys, removed base entries, assertion-like suppressions, and broad POM suppression warnings. The candidate is not promoted automatically.

Dashboard and project-scoped memory

report serve detects nearby project-scoped memory and ordinary run artifacts and adds a Standard run / memory / config-merge snapshot to the generated dashboard. The evidence ZIP may include state/memory, the latest orchestration-report.json, generated reports, real project-verification evidence, and config-merge artifacts.

Agent safety rails

kit init and kit bootstrap-opencode write the configured source scope and protected project command files. /supervised-task runs one complete project pipeline, chooses at most one bounded highest-payoff remediation, and reruns the full pipeline. Scope checks and final gates operate on concrete artifacts; missing evidence remains a blocker.