Configuration Reference

Complete reference for TestBeats configuration options and file structure.

Configuration Methods

TestBeats supports multiple configuration approaches:

1. Configuration file - Comprehensive setup for complex scenarios
2. Environment variables - Dynamic configuration for CI/CD

Configuration File

The configuration file (.testbeats.json) provides the most flexible way to configure TestBeats:

{
  "api_key": "api-keyabcdef",
  "project": "my-awesome-project",
  "run": "Build 123 - main",
  "targets": [
    {
      "name": "slack",
      "condition": "fail",
      "inputs": {
        "url": "https://hooks.slack.com/services/...",
        "publish": "failure-details"
      }
    }
  ],
  "results": [
    {
      "type": "junit",
      "files": ["**/test-results.xml"]
    }
  ],
  "extensions": [
    {
      "name": "mentions",
      "inputs": {
        "users": ["[email protected]"]
      }
    }
  ]
}

Top-Level Properties

Property	Type	Required	Description
api_key	string	No	TestBeats Portal API key
project	string	No	Project identifier
run	string	No	Run identifier or description
targets	array	Yes	Communication targets configuration
results	array	Yes	Test result sources
extensions	array	No	Additional processing extensions

Targets Configuration

Each target represents a communication channel or data destination:

{
  "name": "slack",
  "condition": "fail",
  "inputs": {
    "url": "https://hooks.slack.com/services/...",
    "publish": "test-summary"
  }
}

Target Properties

Property	Type	Required	Description
name	string	Yes	Target type (slack, teams, chat, etc.)
condition	string	No	When to send notifications
inputs	object	Yes	Target-specific configuration

Results Configuration

Define where TestBeats should find test results:

{
  "type": "junit",
  "files": ["**/test-results.xml", "reports/*.xml"]
}

Result Properties

Property	Type	Required	Description
type	string	Yes	Result format (junit, testng, mocha, etc.)
files	array	Yes	File paths or glob patterns

Supported Formats

• junit - JUnit XML format
• testng - TestNG XML format
• mocha - Mocha JSON format
• cucumber - Cucumber JSON format
• nunit - NUnit XML format
• xunit - xUnit XML format
• mstest - MSTest TRX format

Extensions Configuration

Add additional processing capabilities:

{
  "name": "mentions",
  "condition": "fail",
  "inputs": {
    "users": ["[email protected]"],
    "teams": ["dev-team"]
  }
}

Extension Properties

Property	Type	Required	Description
name	string	Yes	Extension type
condition	string	No	When to apply extension
inputs	object	Varies	Extension-specific configuration

Environment Variables

All configuration values support environment variable substitution:

{
  "api_key": "${TESTBEATS_API_KEY}",
  "project": "${CI_PROJECT_NAME}",
  "targets": [
    {
      "name": "slack",
      "inputs": {
        "url": "${SLACK_WEBHOOK_URL}"
      }
    }
  ]
}

Conditions

Conditions allows teams to fine-tune the publishing process to meet their specific needs, ensuring that they receive only the information they require in real-time.

We can specify the conditions under which each target or extension to run. By default, a target or extension will have default condition tied to the test results. For example, targets like slack or teams will run for all the test runs and extensions like report-portal-analysis or mentions will only run when there are test failures.

Condition (Test Results)

• pass
• fail
• passOrFail
• always
• never

{
  "targets": [
    {
      "name": "teams",
      "condition": "pass",
      "inputs": {
        "url": "<teams-success-channel-incoming-webhook-url>"
      }
    },
     {
      "name": "teams",
       "condition": "fail",
      "inputs": {
        "url": "<teams-failure-channel-incoming-webhook-url>"
      }
    }
  ],
  "results": [
    {
      "type": "testng",
      "files": ["path/to/testng-results.xml"]
    }
  ]
}

Condition (Dynamic)

Conditions can also support javascript expressions that returns a boolean. For example, take a look at enabling a extension based on environment variable GIT_BRANCH.

{
  "targets": [
    {
      "name": "teams",
      "inputs": {
        "url": "<teams-incoming-webhook-url>"
      },
      "extensions": [
        {
          "name": "mentions",
          "condition": "{GIT_BRANCH} === 'main'",
          "inputs": {
            "users": [
              {
                "name": "Jon",
                "teams_upn": "[email protected]"
              }
            ]
          }
        }
      ]
    }
  ],
  "results": [
    {
      "type": "testng",
      "files": ["path/to/testng-results.xml"]
    }
  ]
}

Condition (Function)

The function should return a boolean and it can be asynchronous.

const config = {
  "targets": [
     {
      "name": "teams",
       "condition": async ({ target, result }) => {
          return result.failed > 2;
       },
      "inputs": {
        "url": "<teams-failure-channel-incoming-webhook-url>"
      }
    }
  ],
  "results": [
    {
      "type": "testng",
      "files": ["path/to/testng-results.xml"]
    }
  ]
}

Command-Line Override

Command-line arguments override configuration file values:

# Configuration file specifies Slack, but command overrides with Teams
npx testbeats publish -c config.json --teams $TEAMS_WEBHOOK

Configuration Examples

Simple Slack Notification

{
  "targets": [
    {
      "name": "slack",
      "inputs": {
        "url": "${SLACK_WEBHOOK_URL}"
      }
    }
  ],
  "results": [
    {
      "type": "junit",
      "files": ["test-results.xml"]
    }
  ]
}

Multi-Target with Conditions

{
  "targets": [
    {
      "name": "slack",
      "condition": "fail",
      "inputs": {
        "url": "${SLACK_WEBHOOK_URL}",
        "publish": "failure-details"
      }
    },
    {
      "name": "teams",
      "inputs": {
        "url": "${TEAMS_WEBHOOK_URL}",
        "publish": "test-summary-slim"
      }
    }
  ],
  "results": [
    {
      "type": "junit",
      "files": ["**/junit.xml"]
    }
  ]
}

Complete Configuration

{
  "api_key": "${TESTBEATS_API_KEY}",
  "project": "${CI_PROJECT_NAME}",
  "run": "Build ${CI_PIPELINE_ID} - ${CI_COMMIT_REF_NAME}",
  "targets": [
    {
      "name": "slack",
      "condition": "fail",
      "inputs": {
        "url": "${SLACK_WEBHOOK_URL}",
        "publish": "failure-details",
        "title": "🚨 Test Failures",
        "title_link": "${CI_PIPELINE_URL}",
        "only_failures": true
      }
    },
    {
      "name": "teams",
      "inputs": {
        "url": "${TEAMS_WEBHOOK_URL}",
        "publish": "test-summary",
        "title": "📊 Test Results"
      }
    }
  ],
  "results": [
    {
      "type": "junit",
      "files": ["**/test-results.xml", "**/junit.xml"]
    },
    {
      "type": "testng",
      "files": ["**/testng-results.xml"]
    }
  ],
  "extensions": [
    {
      "name": "mentions",
      "condition": "fail",
      "inputs": {
        "users": ["[email protected]"],
        "teams": ["qa-team"]
      }
    },
    {
      "name": "hyperlinks",
      "inputs": {
        "links": [
          {
            "text": "View Build",
            "url": "${CI_PIPELINE_URL}"
          }
        ]
      }
    }
  ]
}

Related Documentation

• Environment Variables - All supported variables
• Targets Reference - Target-specific configuration options
• Extensions Reference - Extension configuration details