TestBeats

Appearance

Environment Variables ​

TestBeats supports environment variables for dynamic configuration values. This allows you to keep sensitive information like API keys and webhook URLs out of your configuration files.

Using Environment Variables ​

To use environment variables in your configuration file, wrap the variable name inside {}:

json
{
  "api_key": "{TEST_BEATS_API_KEY}",
  "targets": [
    {
      "name": "slack",
      "inputs": {
        "url": "{SLACK_WEBHOOK_URL}"
      }
    },
    {
      "name": "teams",
      "inputs": {
        "url": "{TEAMS_WEBHOOK_URL}"
      }
    }
  ]
}

.env File Support ​

TestBeats automatically reads environment variables from a .env file located in the same directory where TestBeats is executed.

Example .env file: ​

bash
# TestBeats Portal Configuration
TEST_BEATS_API_KEY=api-keyabcdef
TEST_BEATS_PROJECT=my-project
TEST_BEATS_RUN=nightly-tests

# Notification Webhooks
SLACK_WEBHOOK_URL=<slack-webhook-url>
TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/...

# CI/CD Overrides
TEST_BEATS_CI_NAME=GitHub Actions
TEST_BEATS_CI_REPOSITORY_NAME=my-org/my-repo

.env File Location

The .env file must be located in the same directory where TestBeats is executed. TestBeats will not search parent directories for .env files.

Pre-defined Environment Variables ​

TestBeats Portal Variables ​

These variables configure TestBeats Portal integration:

VariableDescriptionExample
TEST_BEATS_API_KEYTestBeats Portal API keyapi-keyabcdef
TEST_BEATS_PROJECTProject name for portal organizationmy-project
TEST_BEATS_RUNCustom run name for this executionnightly-tests
TEST_BEATS_DELAYDelay between fetching analysis from portal (ms)3000

CI/CD Information Variables ​

These variables override CI/CD environment detection:

VariableDescriptionExample
TEST_BEATS_CI_NAMEName of the CI providerGitHub Actions
TEST_BEATS_CI_GITName of the Git providerGitHub
TEST_BEATS_CI_REPOSITORY_URLRepository URLhttps://github.com/owner/repo
TEST_BEATS_CI_REPOSITORY_NAMERepository nameowner/repo
TEST_BEATS_CI_REPOSITORY_REFBranch name or pull requestmain or refs/pull/123/merge
TEST_BEATS_CI_REPOSITORY_COMMIT_SHAGit commit SHAabc123def456...
TEST_BEATS_CI_BUILD_URLBuild URLhttps://github.com/owner/repo/actions/runs/123
TEST_BEATS_CI_BUILD_NUMBERBuild number123
TEST_BEATS_CI_BUILD_NAMEBuild nameCI Build
TEST_BEATS_CI_BUILD_REASONBuild reasonpush or pull_request
TEST_BEATS_CI_USERUser who triggered the buildjohn.doe

Common Usage Patterns ​

1. Separate Environments ​

Use different environment variables for different environments:

bash
# Development
TEST_BEATS_PROJECT=my-project-dev
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/.../dev-channel

# Production
TEST_BEATS_PROJECT=my-project-prod
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/.../prod-channel

2. CI/CD Secrets ​

Store sensitive values in your CI/CD platform's secrets management:

GitHub Actions:

yaml
env:
  TEST_BEATS_API_KEY: ${{ secrets.TEST_BEATS_API_KEY }}
  SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

GitLab CI:

yaml
variables:
  TEST_BEATS_API_KEY: $TEST_BEATS_API_KEY
  SLACK_WEBHOOK_URL: $SLACK_WEBHOOK_URL

Jenkins:

groovy
environment {
  TEST_BEATS_API_KEY = credentials('testbeats-api-key')
  SLACK_WEBHOOK_URL = credentials('slack-webhook-url')
}

3. Local Development ​

Create a .env file for local development:

bash
# .env (local development)
TEST_BEATS_API_KEY=tb_dev_key_123
TEST_BEATS_PROJECT=my-project-local
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/.../dev-channel

# Override CI detection for local testing
TEST_BEATS_CI_NAME=Local Development
TEST_BEATS_CI_USER=developer

Environment Variable Priority ​

TestBeats resolves environment variables in the following order (highest to lowest priority):

  1. System environment variables - Set via export or CI/CD
  2. .env file - Local .env file in execution directory
  3. Default values - Built-in defaults where applicable

Validation and Debugging ​

Check Environment Variables ​

bash
# List all TestBeats-related environment variables
env | grep TEST_BEATS

# Check specific variables
echo "API Key: $TEST_BEATS_API_KEY"
echo "Project: $TEST_BEATS_PROJECT"
echo "Slack URL: $SLACK_WEBHOOK_URL"

Test Variable Substitution ​

bash
# Test if variables are being resolved
testbeats publish --verbose \
  --config config.json \
  --junit "results/*.xml"

Common Issues ​

  1. Variable not found:

    Error: Environment variable SLACK_WEBHOOK_URL not found

    Solution: Ensure the variable is set and exported:

    bash
    export SLACK_WEBHOOK_URL="https://hooks.slack.com/..."

  2. Incorrect syntax:

    json
    // ❌ Wrong
"url": "$SLACK_WEBHOOK_URL"
"url": "${SLACK_WEBHOOK_URL}"

// âś… Correct
"url": "{SLACK_WEBHOOK_URL}"

  3. .env file not found:

    Warning: .env file not found

    Solution: Ensure .env file is in the same directory where TestBeats runs.

Security Best Practices ​

1. Never Commit Secrets ​

bash
# Add to .gitignore
echo ".env" >> .gitignore
echo "*.env" >> .gitignore

2. Use CI/CD Secrets ​

  • GitHub Actions: Repository/Organization secrets
  • GitLab CI: CI/CD variables (mark as masked)
  • Jenkins: Credentials plugin
  • Azure DevOps: Variable groups (mark as secret)

3. Rotate Secrets Regularly ​

  • Update API keys periodically
  • Regenerate webhook URLs
  • Update environment variables/secrets in CI/CD

4. Validate in CI/CD ​

yaml
# GitHub Actions example
- name: Validate environment
  run: |
    if [ -z "$TEST_BEATS_API_KEY" ]; then
      echo "ERROR: TEST_BEATS_API_KEY not set"
      exit 1
    fi
    if [ -z "$SLACK_WEBHOOK_URL" ]; then
      echo "ERROR: SLACK_WEBHOOK_URL not set"
      exit 1
    fi

Examples ​

Complete Configuration with Environment Variables ​

json
{
  "api_key": "{TEST_BEATS_API_KEY}",
  "project": "{TEST_BEATS_PROJECT}",
  "run": "{TEST_BEATS_RUN}",
  "targets": [
    {
      "name": "slack",
      "condition": "fail",
      "inputs": {
        "url": "{SLACK_WEBHOOK_URL}",
        "channel": "{SLACK_CHANNEL}"
      }
    },
    {
      "name": "teams",
      "condition": "pass-fail",
      "inputs": {
        "url": "{TEAMS_WEBHOOK_URL}"
      }
    }
  ],
  "results": [
    {
      "type": "junit",
      "files": ["{JUNIT_RESULTS_PATH}"]
    }
  ],
  "extensions": [
    {
      "name": "ci-info"
    }
  ]
}

Corresponding .env file ​

bash
# Portal Configuration
TEST_BEATS_API_KEY=api-keyabcdef
TEST_BEATS_PROJECT=my-awesome-project
TEST_BEATS_RUN=automated-tests

# Notification Configuration
SLACK_WEBHOOK_URL=<slack-webhook-url>
SLACK_CHANNEL=#test-alerts
TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/...

# Test Results Configuration
JUNIT_RESULTS_PATH=test-results/*.xml

# CI/CD Override (optional)
TEST_BEATS_CI_NAME=Custom CI
TEST_BEATS_CI_REPOSITORY_NAME=my-org/my-project

See Also ​

Released under the MIT License.

Copyright © 2025 TestBeats