Added more context for running tests suites with Laravel projects

Author: jaydrogers

resources/boost/guidelines/core.blade.php

@@ -5,10 +5,9 @@
 ## Key facts
 
 - Spin follows Docker Compose syntax exactly — `spin up` runs `docker compose up`, `spin run` runs `docker compose run`, etc.
-- Projects use a **Docker Compose overrides** pattern: a base `docker-compose.yml` merged with `docker-compose.dev.yml` (local) or `docker-compose.prod.yml` (production).
+- Projects use a **Docker Compose overrides** pattern: a base `docker-compose.yml` merged with `docker-compose.$SPIN_ENV.yml`. `SPIN_ENV` defaults to `dev` (→ `docker-compose.dev.yml`). Common values: `dev`, `ci`, `prod`.
 - Laravel projects use `serversideup/php` Docker images (fpm-nginx, fpm-apache, frankenphp, cli).
 - The `.infrastructure/` folder stores configuration files (`conf/`) and gitignored volume data (`volume_data/`).
-- `SPIN_ENV` defaults to `dev`. Running `spin up` uses `docker-compose.yml` + `docker-compose.dev.yml`.
 - In Docker, services connect via container name as hostname (`DB_HOST=mysql`, `REDIS_HOST=redis`), not `localhost`.
 
 ## Essential commands
@@ -17,14 +16,54 @@
 |---------|---------|
 | `spin up` | Start development environment (foreground) |
 | `spin up --build` | Start and rebuild containers (recommended default if custom Dockerfile is used) |
-| `spin run <service> <cmd>` | Run a one-off command in a new container |
-| `spin exec <service> <cmd>` | Run a command in a running container |
+| `spin exec <service> <cmd>` | Run a command in a running container (reuses live container, near-instant) |
+| `spin run <service> <cmd>` | Run a one-off command in a new container (use when the stack is not running) |
 | `spin deploy <env>` | Deploy to a provisioned server |
 | `spin provision` | Provision and configure servers |
 
+### `spin exec` vs `spin run`
+
+- **`spin exec`** — use when the stack is running. Reuses the live container. This is the right default for `artisan`, `composer`, `npm`, tests, and ad-hoc commands during development.
+- **`spin run`** — use when the stack is not running, or when a fresh container with different env vars or isolated state is needed. Creates (and removes) a new container each invocation.
+
+### The `-T` flag (disable pseudo-TTY)
+
+Compose auto-detects TTY by default, so interactive use from a terminal usually works without `-T`. **In AI agent, CI, and other subprocess contexts**, that auto-detection can misfire — Compose sees a TTY on stdin while downstream output is being captured, which can cause hangs, ANSI-garbled output, or prompts with nowhere to respond.
+
+Pass `-T` as a defensive default when running commands from an AI agent, CI pipeline, or any wrapper script:
+
+```bash
+./vendor/bin/spin exec -T php php artisan test
+./vendor/bin/spin run  -T php composer install
+```
+
+Omit `-T` when interactivity is actually needed (`artisan tinker` without `--execute`, interactive `make:*` prompts, `spin exec php bash`).
+
+### Running Laravel tests
+
+Prefer the **already-running dev stack** — it's faster than spinning up a parallel CI stack:
+
+```bash
+./vendor/bin/spin exec -T php php artisan test
+./vendor/bin/spin exec -T php php artisan test --filter=ExampleTest
+```
+
+`php artisan test` works for both PHPUnit and Pest. If the project exposes a `composer test` script, prefer that via `spin exec -T php composer test`.
+
+**Before assuming the dev stack is enough, inspect the test config** (`phpunit.xml`, `phpunit.xml.dist`, or `phpunit.dist.xml`):
+
+- If `<php>` overrides `DB_CONNECTION` to `sqlite` with `DB_DATABASE=:memory:` (and `CACHE_STORE`/`QUEUE_CONNECTION`/`SESSION_DRIVER` set to `array`/`sync`), tests are self-contained — the dev stack is plenty.
+- If the test config uses the real database/cache services, the dev stack usually still works. Reach for `SPIN_ENV=ci` only when CI parity is needed (reproducing a CI-only failure, matching exact service versions, dry-running the pipeline). See the **spin-laravel-development** skill's `TESTING.md` for the full CI-parity workflow.
+
 ## When to activate the full skill
 
-For tasks involving Docker Compose configuration, Dockerfile changes, `serversideup/php` image settings, adding Laravel services (databases, queues, Horizon, Reverb), server provisioning, deployment, or troubleshooting containerized environments — activate the **spin-laravel-development** skill.
+Activate the **spin-laravel-development** skill for tasks involving:
+- Docker Compose configuration or Dockerfile changes
+- `serversideup/php` image settings
+- Adding Laravel services (databases, queues, Horizon, Reverb)
+- Running tests with CI parity (`SPIN_ENV=ci`)
+- Running multiple Compose environments in parallel
+- Server provisioning, deployment, or troubleshooting containerized environments
 
 ## Laravel Boost MCP setup
 
@@ -44,7 +83,20 @@
 spin run php php artisan boost:install
 ```
 
-**IMPORTANT:** `spin-mcp-wait.sh` is exclusively for MCP server startup. NEVER use it to run commands. Always use `spin run` or `spin exec` for running commands (e.g., `spin run php composer install`).
+**IMPORTANT:** `spin-mcp-wait.sh` is exclusively for MCP server startup. NEVER use it to run commands. Always invoke `spin exec` (running stack) or `spin run` (stopped stack) directly.
+
+If this error appears, drop `spin-mcp-wait.sh` and invoke `spin` directly:
+
+```
+Error: spin-mcp-wait.sh is only for starting the MCP server. Use 'spin' directly instead.
+```
+
+Correct:
+
+```bash
+./vendor/bin/spin exec -T php php artisan test
+./vendor/bin/spin run -T php php artisan migrate
+```
 
 ## Templates
 

resources/boost/skills/spin-laravel-development/COMMANDS.md

@@ -73,15 +73,21 @@ Examples:
 ```bash
 spin run php composer install
 spin run php php artisan migrate
-spin run node yarn install
+spin run node npm install
+spin run -T php composer install       # Defensive -T for AI/CI/subprocess contexts
 ```
 
 Spin-specific options:
 - `--skip-pull` — Do not automatically pull images
 - `--force-pull` — Pull images regardless of cache
 
+Key Docker Compose options:
+- `-T` — Disable pseudo-TTY allocation. Compose auto-detects TTY by default, so terminal use works without it. Pass `-T` as a defensive default when invoking from an AI agent, CI pipeline, or subprocess — auto-detection can misfire there and cause hangs or garbled output.
+
 The container is automatically removed after the command completes. Container dependencies are not started.
 
+Use `spin run` when the stack is not running or when isolated state / different env vars are needed. If the stack is already running, prefer `spin exec` — it reuses the live container and is near-instant.
+
 ### `spin exec`
 
 Run a command in a **currently running** container (requires `spin up` to be active).
@@ -90,12 +96,20 @@ Run a command in a **currently running** container (requires `spin up` to be act
 spin exec [OPTIONS] SERVICE COMMAND
 ```
 
-Example:
+Examples:
 
 ```bash
-spin exec php php artisan tinker
+spin exec php php artisan test
+spin exec php composer install
+spin exec php php artisan tinker           # Interactive — no -T needed
+spin exec -T php php artisan test          # Defensive -T for AI/CI/subprocess contexts
 ```
 
+Key Docker Compose options:
+- `-T` — Disable pseudo-TTY allocation. Compose auto-detects TTY by default, so terminal use works without it. Pass `-T` as a defensive default when invoking from an AI agent, CI pipeline, or subprocess — auto-detection can misfire there, causing hangs, ANSI-garbled output, or prompts with nowhere to respond.
+
+`spin exec` is the default choice for `artisan`, `composer`, `npm`, and ad-hoc commands during active development.
+
 ### `spin logs`
 
 View container logs.

resources/boost/skills/spin-laravel-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spin-laravel-development
-description: "Develops and deploys Laravel applications using Spin and serversideup/php Docker images. Covers Docker Compose configuration, development environment setup, container commands, Laravel service configuration (databases, queues, Horizon, Reverb), server provisioning, and deployment workflows. Use when working with Spin, Docker Compose files, serversideup/php images, spin commands, configuring Laravel services in Docker, or deploying Laravel apps to production servers."
+description: "Develops, tests, and deploys Laravel applications using Spin and serversideup/php Docker images. Covers Docker Compose configuration, development environment setup, container commands, running Laravel tests (PHPUnit and Pest), SPIN_ENV selection and CI parity, parallel Compose environments, Laravel service configuration (databases, queues, Horizon, Reverb), server provisioning, and deployment workflows. Use when working with Spin, Docker Compose files, serversideup/php images, spin commands, running artisan test, configuring Laravel services in Docker, or deploying Laravel apps to production servers."
 ---
 
 # Spin Laravel Development
@@ -13,6 +13,7 @@ description: "Develops and deploys Laravel applications using Spin and serversid
 - [Project structure](#project-structure)
 - [Dockerfile pattern](#dockerfile-pattern)
 - [Development workflow](#development-workflow)
+- [Running tests](#running-tests)
 - [serversideup/php images](#serversideupphp-images)
 - [Laravel services](#laravel-services)
 - [Deployment](#deployment)
@@ -24,7 +25,8 @@ description: "Develops and deploys Laravel applications using Spin and serversid
 
 - **NEVER** run commands that could destroy data without explicitly confirming with the user first. This includes `docker system prune`, `docker volume rm`, dropping databases, removing services, or any destructive operation.
 - If Spin fails to run, it is likely because Docker Desktop is not started. Check with `docker info`. If Docker is not running, tell the user to start Docker Desktop and offer to retry before continuing.
-- Always prefer `spin run` over `spin exec` for one-off commands — it is safer because it creates an isolated container.
+- Prefer `spin exec <service> <cmd>` when the stack is running — it reuses the live container and is near-instant. Use `spin run` when the stack is not running or isolated state is needed.
+- Pass `-T` as a defensive default when invoking commands from an AI agent, CI, or subprocess context. Compose auto-detects TTY in regular terminals, but that detection can misfire when wrapped, causing hangs or garbled output.
 
 ## Laravel Boost MCP
 
@@ -38,12 +40,18 @@ BOOST_COMPOSER_EXECUTABLE_PATH="./vendor/bin/spin run php composer"
 BOOST_NPM_EXECUTABLE_PATH="./vendor/bin/spin run node npm"
 ```
 
-**NEVER use `spin-mcp-wait.sh` to run commands.** It is exclusively for MCP server startup. The script will refuse non-MCP invocations with an error. Always use `spin run` or `spin exec` for running commands:
+**NEVER use `spin-mcp-wait.sh` to run commands.** It is exclusively for MCP server startup. The script will refuse non-MCP invocations with this error:
+
+```
+Error: spin-mcp-wait.sh is only for starting the MCP server. Use 'spin' directly instead.
+```
+
+If that error appears, drop `spin-mcp-wait.sh` and invoke `spin` directly:
 
 ```bash
-spin run php composer install          # Correct
-spin run php php artisan migrate       # Correct
-spin-mcp-wait.sh spin run php ...     # WRONG — never do this
+./vendor/bin/spin exec -T php php artisan test          # Correct
+./vendor/bin/spin run  -T php php artisan migrate       # Correct
+./vendor/bin/spin-mcp-wait.sh ./vendor/bin/spin run php # WRONG — never do this
 ```
 
 ## How Spin works
@@ -184,17 +192,27 @@ spin up -d         # Detached mode (background)
 
 ### Running commands
 
-Syntax: `spin run <service> <command>` — the first argument is the **service name** from `docker-compose.yml`.
+Syntax: `spin <exec|run> [-T] <service> <command>` — the service argument is the **service name** from `docker-compose.yml`.
 
 ```bash
-spin run php composer install
-spin run php php artisan migrate       # First "php" = service, second "php" = binary
-spin run php php artisan make:model Post
-spin run node yarn install
-spin run node yarn dev
+spin exec php composer install
+spin exec php php artisan migrate       # First "php" = service, second "php" = binary
+spin run  php php artisan make:model Post
+spin exec node npm install
+spin exec node npm run dev
 ```
 
-**`run` vs `exec`**: Use `spin run` for one-off commands (creates a new container, runs, exits). Use `spin exec` to execute in an already-running container (requires `spin up` to be active). Prefer `spin run` for package installs, migrations, artisan commands.
+**`exec` vs `run`**:
+
+- **`spin exec`** reuses the live container from an already-running stack. Near-instant. Default for `artisan`, `composer`, `npm`, and ad-hoc commands during development.
+- **`spin run`** creates a new container each invocation. Use when the stack is not running, or when isolated state / different env vars are needed.
+
+**The `-T` flag**: Compose auto-detects TTY, so interactive terminal usage works without `-T`. Add `-T` as a defensive default when invoking from an AI agent, CI pipeline, or wrapper script — auto-detection can misfire in those contexts, causing hangs or ANSI-garbled output:
+
+```bash
+./vendor/bin/spin exec -T php php artisan test     # AI/CI-safe
+./vendor/bin/spin exec php artisan tinker          # Interactive — omit -T
+```
 
 ### Volume mounting
 
@@ -242,6 +260,25 @@ SPIN_APP_DOMAIN=laravel.dev.test
 
 See [COMMANDS.md](COMMANDS.md) for the complete 26-command reference.
 
+## Running tests
+
+Prefer the **already-running dev stack** — it's faster than spinning up a parallel CI stack:
+
+```bash
+./vendor/bin/spin exec -T php php artisan test
+./vendor/bin/spin exec -T php php artisan test --filter=ExampleTest
+./vendor/bin/spin exec -T php composer test    # If the project exposes a composer test script
+```
+
+`php artisan test` works for both PHPUnit and Pest.
+
+**Before assuming the dev stack is enough, inspect the test config** (`phpunit.xml`, `phpunit.xml.dist`, or `phpunit.dist.xml`):
+
+- If the `<php>` block overrides `DB_CONNECTION` to `sqlite` with `DB_DATABASE=:memory:` (and cache/queue/session set to `array`/`sync`), tests are self-contained — the dev stack is plenty.
+- If the test config uses the real database/cache services, the dev stack usually still works. Reach for `SPIN_ENV=ci` only when CI parity is explicitly needed: reproducing a CI-only failure, matching exact service versions, or dry-running the pipeline before pushing.
+
+See [TESTING.md](TESTING.md) for the full CI-parity workflow, parallel Compose environments, and the override-network gotcha.
+
 ## serversideup/php images
 
 Choose the right variant:
@@ -332,6 +369,9 @@ The `.spin.yml` file defines users, providers, servers, and environments. Suppor
 | Stale containers | Use `spin up --build` to rebuild |
 | DB password not working | Credentials are only created on first container init — remove volume to reset |
 | Permission errors in container | Check `SPIN_USER_ID`/`SPIN_GROUP_ID` match host user |
+| Command hangs in AI/CI wrapper | Compose TTY auto-detection misfired — add `-T` to `spin exec`/`spin run` |
+| `SPIN_ENV=ci` clobbered dev containers | `docker-compose.ci.yml` needs its own `name:` project (see [TESTING.md](TESTING.md)) |
+| "host not found" between services on `SPIN_ENV=ci` | Override network didn't include inherited services (see [TESTING.md](TESTING.md)) |
 
 See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for remote server debugging and Docker Swarm troubleshooting.
 
@@ -343,4 +383,5 @@ See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for remote server debugging and Doc
 | [DOCKER-IMAGES.md](DOCKER-IMAGES.md) | Configuring serversideup/php images, environment variables, health checks |
 | [DEPLOYMENT.md](DEPLOYMENT.md) | Setting up deployment pipelines or running `spin deploy` |
 | [LARAVEL-SERVICES.md](LARAVEL-SERVICES.md) | Adding databases, queues, Horizon, Reverb, or other Docker services |
-| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Debugging issues on remote servers or Docker Swarm |
+| [TESTING.md](TESTING.md) | Running Laravel tests, `SPIN_ENV=ci` CI parity, parallel Compose stacks |
+| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Debugging issues on remote servers, Docker Swarm, or Compose network/stack collisions |