Expose --recreate flag to ddev env test (DataDog#22521)

* Expose --recreate flag to `ddev env test`

* Add changelog and ingore-state handling

* Add AGENTS.md instructions for recreating testing environments

* Prefer `--recreate` in AGENT.md docs

Author: dkirov-dd

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## General Development Guidelines
 
-* Auto-format code with `ddev test -fs`.
+- Auto-format code with `ddev test -fs`.
 
 ## Python Type Hinting
 
@@ -52,16 +52,19 @@ Run unit and integration tests with `ddev --no-interactive test <INTEGRATION>`.
 Run E2E tests by following these steps:
 
 1. List available environments for the integration:
+
    ```shell
    ddev env show <INTEGRATION>
    ```
 
 2. Start a specific environment:
+
    ```shell
    ddev env start --dev <INTEGRATION> <ENV>
    ```
 
 3. Run the E2E tests in that environment:
+
    ```shell
    ddev env test --dev <INTEGRATION> <ENV>
    ```
@@ -82,6 +85,20 @@ ddev env stop pgbouncer py3.11-1.23
 
 Run specific tests with `ddev --no-interactive test <INTEGRATION> -- -k <PYTEST_FILTER_STRING>`, for example `ddev --no-interactive test kuma -- -k test_code_class_injection -s`.
 
+### Recreating Environments
+
+Add `--recreate` to recreate test environments from scratch:
+
+```shell
+# Unit/integration tests - recreates Hatch environments
+ddev test --recreate <INTEGRATION>
+
+# E2E tests - recreates both Hatch environments and Docker containers/volumes
+ddev env test --dev --recreate <INTEGRATION> <ENV>
+```
+
+For E2E tests, `--recreate` performs `docker compose down --volumes` followed by `docker compose up -d --force-recreate`.
+
 ## Code Formatting
 
 Format code with `ddev test -fs <INTEGRATION>`. For example, for the pgbouncer integration, run `ddev test -fs pgbouncer`.
@@ -96,9 +113,9 @@ Changelog files are named `<PR_NUMBER>.<TYPE>` and placed in the integration's `
 
 ### Version Bumping Behavior
 
-* `fixed` - Bug fixes. Bumps the **patch** version (e.g., 1.0.0 → 1.0.1)
-* `added` - New features. Bumps the **minor** version (e.g., 1.0.0 → 1.1.0)
-* `changed` - Breaking changes or significant modifications. Bumps the **major** version (e.g., 1.0.0 → 2.0.0)
+- `fixed` - Bug fixes. Bumps the **patch** version (e.g., 1.0.0 → 1.0.1)
+- `added` - New features. Bumps the **minor** version (e.g., 1.0.0 → 1.1.0)
+- `changed` - Breaking changes or significant modifications. Bumps the **major** version (e.g., 1.0.0 → 2.0.0)
 
 ### Command Format
 

ddev/changelog.d/22521.added

@@ -0,0 +1 @@
+Add --recreate/-r flag to ddev env test command to recreate environments from scratch before running tests

ddev/src/ddev/cli/env/test.py

@@ -39,6 +39,7 @@
     multiple=True,
     help='Environment variables to pass to the Agent e.g. -e DD_URL=app.datadoghq.com -e DD_API_KEY=foobar',
 )
+@click.option('--recreate', '-r', is_flag=True, help='Recreate environments from scratch')
 @click.option('--junit', is_flag=True, hidden=True)
 @click.option('--python-filter', envvar='PYTHON_FILTER', hidden=True)
 @click.option('--new-env', is_flag=True, hidden=True)
@@ -53,6 +54,7 @@ def test_command(
     local_base: bool,
     agent_build: str | None,
     extra_env_vars: tuple[str, ...],
+    recreate: bool,
     junit: bool,
     python_filter: str | None,
     new_env: bool,
@@ -121,6 +123,11 @@ def test_command(
     active = set(active_envs)
     for env_name in env_names:
         env_active = env_name in active
+
+        # If recreating and environment is already active, stop it first to get a fresh environment
+        if recreate and env_active:
+            ctx.invoke(stop, intg_name=intg_name, environment=env_name, ignore_state=False)
+
         ctx.invoke(
             start,
             intg_name=intg_name,
@@ -130,7 +137,7 @@ def test_command(
             agent_build=agent_build,
             extra_env_vars=extra_env_vars,
             hide_help=True,
-            ignore_state=env_active,
+            ignore_state=env_active and not recreate,
         )
 
         env_data = storage.get(integration.name, env_name)
@@ -147,6 +154,7 @@ def test_command(
                     test,
                     target_spec=f'{intg_name}:{env_name}',
                     pytest_args=pytest_args,
+                    recreate=recreate,
                     junit=junit,
                     hide_header=True,
                     e2e=True,