Add migration script for upgrading from 2.x to 3.x

CHANGELOG.md

@@ -9,6 +9,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - `assertValidationNotContains()` to assert that specific validation rules are absent, ignoring others on the same field.
 - `assertValidationListContains()` and `assertValidationListNotContains()` list helpers.
 - Optional custom `$expected` parameter for `assertValidationForeignKey()` and `assertValidationIsUnique()`.
+- Migration script `migrate.php` to assist upgrading from 2.x to 3.x. See the [migration guide](docs/Migration.md). [#47](https://github.com/orca-services/cakephp-data-validation-testing/issues/47)
 
 ### Changed
 - **BREAKING CHANGE:** Replace `testDataValidation` prefix in all test trait method names with `assertValidation`. E.g. `testDataValidationNotEmpty()` becomes `assertValidationNotEmpty()`.

README.md

@@ -6,7 +6,8 @@ A CakePHP plugin to help testing data validation.
 
 | Plugin Version | CakePHP Compatibility | Branch      | Status    |
 |----------------|-----------------------|-------------| --------- |
-| 2.x            | 5.x                   | cakephp-5.x | Supported |
+| 3.x            | 5.x                   | cakephp-5.x | Supported |
+| 2.x            | 5.x                   | -           | EOL       |
 | 1.x            | 4.x                   | cakephp-4.x | Supported |
 | 0.x            | 2.x                   | cakephp-2.x | EOL       |
 
@@ -22,6 +23,11 @@ See the [installation documentation](docs/Installation.md).
 
 You can use the plugin as shown in [usage documentation](docs/Usage.md).
 
+## Upgrading
+
+See the [migration guide](docs/Migration.md) for upgrading from 2.x to 3.x.
+It includes a migration script that renames the old method calls and lists the places that need a manual review.
+
 ## Versioning
 
 The releases of this plugin are versioned using [SemVer](http://semver.org/).

docs/Migration.md

@@ -5,6 +5,46 @@ This major version bundles two breaking changes:
 1. **Method renames** — [PR #45](https://github.com/orca-services/cakephp-data-validation-testing/pull/45) (closes [#44](https://github.com/orca-services/cakephp-data-validation-testing/issues/44))
 2. **Rule-dedicated methods now check only their own rule** — [PR #40](https://github.com/orca-services/cakephp-data-validation-testing/pull/40) (closes [#38](https://github.com/orca-services/cakephp-data-validation-testing/issues/38))
 
+You can use the [Migration Script](#migration-script) to rename the old method calls automatically
+and to find the places that need a manual review.
+
+---
+
+## Migration Script
+
+The Migration Script does not fully automate the upgrade, but it takes care of the method renames
+and lists everything else you need to review manually. It is shipped with the package,
+so first update the package to 3.x:
+
+```bash
+composer require --dev orca-services/cakephp-data-validation-testing:^3.0 -W
+```
+
+Then run the script from the root of your application:
+
+```bash
+php vendor/orca-services/cakephp-data-validation-testing/migrate.php
+```
+
+The script interactively asks for the directories to migrate (comma separated, default: `tests,plugins`).
+
+What it does:
+
+1. Renames all calls of the old method names to the new ones (see [Method renames](#1-method-renames)).
+   Only method calls and references preceded by `->` or `::` are replaced,
+   so your own test methods with similar names are left untouched.
+2. Replaces calls of the removed `testRules()` with `assertRules()` and lists them for manual review
+   (see [`testRules()` removal](#testrules-removal)).
+3. Lists all calls of rule-dedicated methods for manual review
+   (see [Rule-dedicated methods now check only their own rule](#2-rule-dedicated-methods-now-check-only-their-own-rule)).
+4. Lists old method names it did not replace, e.g. in strings, callables or own methods with the same name.
+
+The script modifies your files in place, so make sure your working tree is clean (e.g. committed in Git) before running it.
+Afterward:
+
+- Review the diff (e.g. `git diff`) and the listed findings.
+- Run your test suite and fix any failing tests.
+
 ---
 
 ## 1. Method renames
@@ -52,10 +92,20 @@ This avoids PHPUnit mistaking them for actual test methods. **No logic changed**
 | `testDataValidationForeignKey()`         | `assertValidationForeignKey()`         |
 | `testDataValidationIsUnique()`           | `assertValidationIsUnique()`           |
 
+### `testRules()` removal
+
+`testRules()` was removed without a direct equivalent. Use `assertRules()` instead, but note the difference in behavior:
+`assertRules()` skips data validation (`validate => false`) and asserts that saving fails,
+while `testRules()` first asserted that there are no validation errors.
+Review each replaced call to make sure the test still covers what you intend.
+
 ---
 
 ## 2. Rule-dedicated methods now check only their own rule
 
 Previously, methods like `assertValidationBoolean()`, `assertValidationEmail()`, `assertValidationInteger()`, etc. compared the **entire** error array for a field against an expected array (or `[]` for valid values). If a field had multiple validation errors, this could hide unrelated errors or cause false failures.
 
 Now these methods assert **only their own rule key** (present or absent), ignoring any other errors on the same field.
+
+Review your calls of these methods, especially where a custom `$expected` array containing several rules is passed,
+and make sure the tests still cover what you intend. The [Migration Script](#migration-script) lists all these calls for you.