Merge pull request #638 from ThomasLandauer/patch-3

Adding upgrading instructions

Author: Arhell

_posts/2022-07-28-codeception-5.markdown

@@ -26,7 +26,7 @@ tests/
   Unit/
 ```
 
-All suite names will have their own namespace, as well as actor and helper classes:
+All suite names have their own namespace, as well as actor and helper classes:
 
 ```php
 <?php
@@ -44,7 +44,53 @@ class LoginCest
 }
 ```
 
-This new directory structure will be generated by running `codecept bootstrap`. The directory structure is set with a new default config, so the previous directory structure is still valid.
+This new directory structure will be generated by running `codecept bootstrap`.
+
+### Upgrading from Codeception 4
+
+Codeception 5 is compatible with the Codeception 4 directory structure. So if you don't want to change your file locations now, just keep your existing `codeception.yml`, and everything's fine.
+
+However, if you want to upgrade to the new Codeception 5 directory structure (recommended), here's the new default `codeception.yml`:
+
+```yaml
+namespace: Tests
+support_namespace: Support
+paths:
+    tests: tests
+    output: tests/_output
+    data: tests/Support/Data
+    support: tests/Support
+    envs: tests/_envs
+actor_suffix: Tester
+extensions:
+    enabled:
+        - Codeception\Extension\RunFailed
+```
+
+Next steps:
+
+1. Rename your suite configuration files:
+    `acceptance.suite.yml` => `Acceptance.suite.yml`
+    `functional.suite.yml` => `Functional.suite.yml`
+    `unit.suite.yml` => `Unit.suite.yml`
+2. Inside those configuration files, update to the new namespace:
+    ```yaml
+    modules:
+        enabled:
+            - Tests\Support\Helper\Unit
+    ```
+3. In your `composer.json`, update to the new namespace:
+    ```json
+    "autoload-dev": {
+        "psr-4": {
+            "Tests\\": "tests/"
+        }
+    },
+    ```
+4. In your `tests/Support/Acceptance|Functional|UnitTester.php` files, update to the new namespace.
+5. Run `vendor/bin/codecept build` to create the files in `tests/Support/_generated`.
+6. Modify the namespaces in all your test/cest files.
+7. Run the tests with capitalized suite names: `vendor/bin/codecept run Unit`
 
 ## Attributes
 
@@ -103,6 +149,10 @@ Also new functions were added:
 * `codecept_pause()` - starts interactive pause anywhere in debug mode
 * `codecept_debug()` - prints a variable to console using Symfony VarDumper
 
+### Upgrading from Codeception 4
+
+Just remove `hoa/console` from your `composer.json`.
+
 ## Sharding
 
 The [Parallel Execution guide](/docs/ParallelExecution) has been rewritten and focused on a new feature: sharding. It is the simplest way to run slow tests (think of acceptance tests first) in parallel on multiple agents.