Environment Configuration

Plyson makes it easy to switch between different API environments without changing your test code. By using environment files, you can manage base URLs, API keys, and other stage-specific variables in one place.

Environment Files

Environment files are stored in the environments/ directory. Plyson supports two formats:

• JSON (*.env.json): Structured configuration with schema support.
• Dotenv (*.env): Standard key-value pairs for environment variables.

For a detailed breakdown of all available fields, see the Environments Reference.

• environments/dev.env.json and/or environments/dev.env -> selected via --env dev
• environments/staging.env.json and/or environments/staging.env -> selected via --env staging

Structure of an Environment File

JSON Format (dev.env.json)

{
  "$schema": "../Project-schema/environment.schema.json",
  "baseUrl": "https://api.dev.json",
  "variables": {
    "API_KEY": "dev_secret_key_123"
  }
}

Dotenv Format (dev.env)

baseUrl=https://api.dev.env
API_KEY=dev_override_key
TIMEOUT=5000

Merging & Priority

If both a .env.json and a .env file exist for the same environment, Plyson merges them. Dotenv files take precedence over JSON files.

Additionally, System Environment Variables (e.g., from your OS or CI/CD pipeline) have the highest priority and will override values from both file formats.

Resolution Priority (Highest to Lowest):

1. System Environment Variables
2. .env File (dev.env)
3. .env.json File (dev.env.json)

CI/CD & System Overrides

You can override any environment variable or the baseUrl using system environment variables. This is particularly useful for passing secrets in CI/CD pipelines without committing them to your repository.

• BASE_URL or baseUrl: Overrides the environment's base URL.
• VARIABLE_NAME: Overrides a variable defined in the environment's variables block.

# Example: Override baseUrl and a specific variable via command line
BASE_URL=https://api.test.com DB_PASSWORD=secret npx plyson run --env dev

Switching Environments

To run your tests against a specific environment, use the --env flag:

npx plyson run --env staging

Default Environment

You can specify a default environment in your project.json so you don't have to provide the flag every time:

{
  "title": "My API Project",
  "defaultEnv": "dev"
}

With this setting, running npx plyson run will automatically target the dev environment.

Best Practices

1. Don't Hardcode URLs: Always use relative paths in your test suites (e.g., /users) and define the baseUrl in your environment files.
2. Variable Overrides: Use environment variables for things that change between stages, such as database IDs or feature flags.