pytest-dotenv

0.5.2 · maintenance · verified Thu Apr 09

pytest-dotenv is a Pytest plugin that facilitates the loading of environment variables from `.env` files before running tests. It integrates seamlessly with Pytest's plugin system, automatically detecting and parsing `.env` files in your project. The current version is 0.5.2, with its last release in June 2020, indicating a stable but infrequently updated project.

Warnings

gotcha By default, `pytest-dotenv` will not override environment variables that are already defined in the process's environment. If you need to force overriding, you must explicitly enable `env_override_existing_values = 1` in your `pytest.ini` or use the `--envfile` CLI option (which always overrides).
Fix: Add `env_override_existing_values = 1` under the `[pytest]` section in your `pytest.ini` file, or use `pytest --envfile path/to/.env`.
gotcha If not explicitly configured, `pytest-dotenv` searches for `.env` files in the working directory and then in ancestor directories. If you have multiple `.env` files or specific naming conventions, ensure you define them using `env_files` in `pytest.ini` to control precedence.
Fix: Specify `env_files = .env.test .env.local .env` in your `pytest.ini` to define a custom loading order and paths. Files are loaded in the order listed.
gotcha Accidentally committing `.env` files, which often contain sensitive credentials, to version control systems like Git is a common security risk.
Fix: Always add `.env` (and any other files containing sensitive data) to your `.gitignore` file to prevent accidental commits.
gotcha Be aware of potential conflicts or unexpected behavior if you are also using other pytest plugins that manage environment variables (e.g., `pytest-env`) or if you manually load `python-dotenv` within your `conftest.py` with different `override` settings. The precedence rules between multiple plugins or manual loading can be complex.
Fix: Standardize on a single method for loading environment variables. If using `pytest-dotenv`, rely on its configuration options. If manual loading is preferred, ensure `autouse=True` fixtures are properly scoped and handle overrides as expected.

Install

pip install pytest-dotenv Install with pip

Imports

No direct imports for basic usage
```
Configuration is primarily done via pytest.ini or command-line options.
```
As a pytest plugin, it integrates automatically upon installation. Explicit imports in test files are generally not required for its core functionality.

Quickstart

To get started, simply install the plugin and create a `.env` file in your project's root directory. pytest-dotenv will automatically load these variables when tests are run. For advanced usage, you can configure custom `.env` file paths or override existing system environment variables using a `pytest.ini` configuration file.

# 1. Create a .env file in your project root:
# .env
MY_SECRET_KEY=supersecretkey123
DATABASE_URL=postgresql://user:password@host:port/dbname

# 2. Create a test file, e.g., test_settings.py:
# test_settings.py
import os

def test_environment_variables_loaded():
    assert os.getenv('MY_SECRET_KEY') == 'supersecretkey123'
    assert os.getenv('DATABASE_URL') == 'postgresql://user:password@host:port/dbname'

# 3. (Optional) Create a pytest.ini for custom configuration:
# pytest.ini
# [pytest]
# env_files = .env.test .env
# env_override_existing_values = 1

# 4. Run pytest from your terminal:
# pytest

view raw JSON →