feat: add BROWSER_ALWAYS_START_WEBSERVER env var

Author: kbond

README.md

@@ -407,7 +407,7 @@ $browser
 Make assertions about json responses using [JMESPath expressions](https://jmespath.org/)
 See the [JMESPath Tutorials](https://jmespath.org/tutorial.html) to learn more.
 
-> **Note**
+> [!NOTE]
 > `mtdowling/jmespath.php` is required: `composer require --dev mtdowling/jmespath.php`.
 
 ```php
@@ -453,14 +453,21 @@ $json = $browser
 ;
 ```
 
-> **Note**
+> [!NOTE]
 > See the [full `zenstruck/assert` expectation API documentation](https://github.com/zenstruck/assert#expectation-api)
 > to see all the methods available on `Zenstruck\Browser\Json`.
 
 ### PantherBrowser
 
 *The `PantherBrowser` is experimental in 1.0 and may be subject to BC Breaks.*
 
+> [!TIP]
+> By default, Panther will not start a web server if it detects one already running
+> with the Symfony CLI. This is likely running in your `dev` environment and will cause
+> unexpected test failures. Set the env variable `BROWSER_ALWAYS_START_WEBSERVER=1`
+> to always start a webserver configured for your current test env when running
+> Panther tests.
+
 This browser has the following extra methods:
 
 ```php
@@ -543,17 +550,18 @@ class MyTest extends PantherTestCase
 
 There are several environment variables available to configure:
 
-| Variable                   | Description                                                                                | Default                            |
-|----------------------------|--------------------------------------------------------------------------------------------|------------------------------------|
-| `BROWSER_SOURCE_DIR`       | Directory to save source files to.                                                         | `./var/browser/source`             |
-| `BROWSER_SCREENSHOT_DIR`   | Directory to save screenshots to (only applies to `PantherBrowser`).                       | `./var/browser/screenshots`        |
-| `BROWSER_CONSOLE_LOG_DIR`  | Directory to save javascript console logs to (only applies to `PantherBrowser`).           | `./var/browser/console-logs`       |
-| `BROWSER_FOLLOW_REDIRECTS` | Whether to follow redirects by default (only applies to `KernelBrowser`).                  | `1` _(true)_                       |
-| `BROWSER_CATCH_EXCEPTIONS` | Whether to catch exceptions by default (only applies to `KernelBrowser`).                  | `1` _(true)_                       |
-| `BROWSER_SOURCE_DEBUG`     | Whether to add request metadata to written source files (only applies to `KernelBrowser`). | `0` _(false)_                      |
-| `KERNEL_BROWSER_CLASS`     | `KernelBrowser` class to use.                                                              | `Zenstruck\Browser\KernelBrowser`  |
-| `PANTHER_BROWSER_CLASS`    | `PantherBrowser` class to use.                                                             | `Zenstruck\Browser\PantherBrowser` |
-| `PANTHER_NO_HEADLESS`      | Disable headless-mode and allow usage of `PantherBrowser::pause()`.                        | `0` _(false)_                      |
+| Variable                         | Description                                                                                                            | Default                            |
+|----------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------|
+| `BROWSER_SOURCE_DIR`             | Directory to save source files to.                                                                                     | `./var/browser/source`             |
+| `BROWSER_SCREENSHOT_DIR`         | Directory to save screenshots to (only applies to `PantherBrowser`).                                                   | `./var/browser/screenshots`        |
+| `BROWSER_CONSOLE_LOG_DIR`        | Directory to save javascript console logs to (only applies to `PantherBrowser`).                                       | `./var/browser/console-logs`       |
+| `BROWSER_FOLLOW_REDIRECTS`       | Whether to follow redirects by default (only applies to `KernelBrowser`).                                              | `1` _(true)_                       |
+| `BROWSER_CATCH_EXCEPTIONS`       | Whether to catch exceptions by default (only applies to `KernelBrowser`).                                              | `1` _(true)_                       |
+| `BROWSER_SOURCE_DEBUG`           | Whether to add request metadata to written source files (only applies to `KernelBrowser`).                             | `0` _(false)_                      |
+| `KERNEL_BROWSER_CLASS`           | `KernelBrowser` class to use.                                                                                          | `Zenstruck\Browser\KernelBrowser`  |
+| `PANTHER_BROWSER_CLASS`          | `PantherBrowser` class to use.                                                                                         | `Zenstruck\Browser\PantherBrowser` |
+| `PANTHER_NO_HEADLESS`            | Disable headless-mode and allow usage of `PantherBrowser::pause()`.                                                    | `0` _(false)_                      |
+| `BROWSER_ALWAYS_START_WEBSERVER` | Always start a webserver configured for your current test env before running tests (only applies to `PantherBrowser`). | `0` _(false)_                      |
 
 ## Extending
 
@@ -818,9 +826,10 @@ Then, depending on the implementation you extended from, set the appropriate env
 
 For the example above, you would set `KERNEL_BROWSER_CLASS=App\Tests\AppBrowser`.
 
-**TIP**: Create a base functional test case so all your tests can use your
-custom browser and use the `@method` annotation to ensure your tests can
-autocomplete your custom methods:
+> [!TIP]
+> Create a base functional test case so all your tests can use your
+> custom browser and use the `@method` annotation to ensure your tests can
+> autocomplete your custom methods:
 
 ```php
 namespace App\Tests;

src/Browser/Test/HasBrowser.php

@@ -64,6 +64,11 @@ protected function pantherBrowser(array $options = [], array $kernelOptions = []
             'console_log_dir' => $_SERVER['BROWSER_CONSOLE_LOG_DIR'] ?? './var/browser/console-logs',
         ];
 
+        if ($_SERVER['BROWSER_ALWAYS_START_WEBSERVER'] ?? null) {
+            $_SERVER['PANTHER_APP_ENV'] = $_SERVER['APP_ENV'] ?? 'test'; // use current environment
+            $_SERVER['SYMFONY_PROJECT_DEFAULT_ROUTE_URL'] = ''; // ignore existing server running with Symfony CLI
+        }
+
         if (self::$primaryPantherClient) {
             $browser = new $class(static::createAdditionalPantherClient(), $browserOptions);
         } else {