How to specify a different .env file for phpunit in Laravel 5?

How to specify a different .env file for phpunit in Laravel 5?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

How to Specify a Different .env File for PHPUnit in Laravel 5

In Laravel 5, the standard workflow involves placing sensitive configuration details like database credentials and API keys directly into the root .env file. This approach keeps secrets out of your version control repository while ensuring the application reads the correct environment at runtime. However, this creates a friction point during development: how do you run PHPUnit tests without committing those secrets or manually editing the shared .env file every time you switch branches?

The common intuition is to create a separate file, perhaps named .env.testing, and instruct phpunit.xml to load it instead. While this seems like a logical separation of concerns, Laravel's architecture does not natively support loading distinct environment files via configuration directives in the way one might expect from frameworks that offer explicit environment switching flags.

The core mechanism Laravel uses for environment management is not file-based pathing but rather an environment variable check. When the application boots, it attempts to load a file named .env relative to the base path. If an environment variable APP_ENV is set to something other than local, production, or testing (depending on version specifics), Laravel falls back to loading .env.testing if that specific file exists.

To achieve the goal of using a dedicated test configuration without altering your main production-ready settings, you must leverage the environment variable mechanism rather than trying to hardcode file paths in phpunit.xml. The solution involves ensuring your testing environment is isolated via shell variables or a CI/CD pipeline setup, rather than relying on a custom directive inside the XML configuration.

Leveraging Environment Variables

The most robust method to isolate test credentials is to set the APP_ENV variable before invoking PHPUnit. When you run the command:

APP_ENV=testing ./vendor/bin/phpunit

Laravel's bootstrap process detects that APP_ENV is set to testing. It then looks for a file named .env.testing in the root directory. If this file exists, Laravel loads it and applies its variables on top of any existing configuration. This allows you to store specific test database credentials, dummy API keys, or intentionally broken configurations (such as disabling cache drivers) strictly within .env.testing.

Because phpunit.xml is primarily responsible for defining test suites, paths, and execution options like verbosity, adding environment-specific file loading logic directly into the XML file is not supported by the framework's internal loader. Attempting to inject a custom path argument into the artisan command wrapper inside phpunit.xml is unnecessary; the framework handles the file switching automatically once the environment variable is present.

Managing Secrets in CI/CD Pipelines

A significant trade-off with this approach is how secrets are managed when your tests run on a Continuous Integration server. Unlike a local developer machine where you can manually set APP_ENV=testing and provide a .env.testing file, a CI runner typically runs in a stateless container or ephemeral environment without access to your local files.

If you rely solely on a .env.testing file in your repository root, you face the original problem: you cannot commit secrets to that file. The industry-standard solution for this scenario is to utilize an encrypted environment file (.env.enc) paired with Laravel's built-in decryption support, or to inject credentials via secure environment variables provided by your CI provider (e.g., DB_DATABASE, DB_USERNAME, and DB_PASSWORD set in GitHub Actions or Jenkins).

When using a CI pipeline, you might configure the test runner to look for .env.testing but populate it with sensitive data through injected environment variables at runtime. This ensures that the file itself never contains plaintext passwords. Alternatively, many teams prefer to keep the production database credentials in the main .env (which is gitignored) and create a minimal .env.testing that only overrides specific non-sensitive settings like cache paths or log levels, while leaving the connection details entirely dependent on CI-injected variables.

Avoiding Common Pitfalls

One common mistake is attempting to hardcode the path to a test environment file within phpunit.xml. The framework does not parse XML for custom .env loading directives. If you try to pass arguments to the artisan command to force a specific file, you will encounter errors because the test:reset or bootstrap logic expects the standard environment resolution flow.

Additionally, be careful not to commit your .env.testing file to version control if it contains any real credentials. Treat this file exactly like your production .env: add it to your .gitignore. The only time you should check in a test-specific environment file is when it contains configuration that is safe to share, such as pointing to an empty SQLite database or a public sandbox API endpoint.

By strictly adhering to the APP_ENV variable convention and managing secrets via CI injection or encrypted files, you maintain the security philosophy of Laravel while gaining the flexibility needed for comprehensive automated testing.

Our network