Configuration Reference

Complete reference for TestBeats configuration options and file structure.

Configuration File

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

json

{
  "api_key": "<your-api-key>",
  "project": "my-awesome-project",
  "run": "Build 123 - main",
  "results": [
    {
      "type": "junit",
      "files": ["**/test-results.xml"]
    }
  ],
  "targets": [
    {
      "name": "slack",
      "condition": "fail",
      "inputs": {
        "url": "<slack-webhook-url>",
        "publish": "failure-details"
      }
    }
  ],
  "extensions": [
    {
      "name": "mentions",
      "inputs": {
        "users": ["[email protected]"]
      }
    }
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}

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
`results`	array	Yes	Test result sources
`targets`	array	No	Communication targets configuration
`extensions`	array	No	Additional processing extensions
`metadata`	object	No	Metadata for the test run

Results Configuration

Define where TestBeats should find test results:

json

{
  "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

Automation Test Results

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

Performance Test Results

jmeter - JMeter XML format

Targets Configuration

Each target represents a communication channel or data destination:

json

{
  "name": "slack",
  "enable": true,
  "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.)
`enable`	boolean	No	Whether to enable this target
`condition`	string	No	When to send notifications
`inputs`	object	Yes	Target-specific configuration
`extensions`	array	No	Local extensions for this target

Extensions Configuration

Add additional processing capabilities:

json

{
  "name": "mentions",
  "enable": true,
  "condition": "fail",
  "hook": "after-summary",
  "order": 1,
  "inputs": {
    "users": ["[email protected]"],
    "teams": ["dev-team"]
  }
}

Extension Properties

Property	Type	Required	Description
`name`	string	Yes	Extension type
`enable`	boolean	No	Whether to enable this extension
`hook`	string	No	When to apply extension (start, after-summary, end)
`order`	number	No	Order of execution
`condition`	string	No	When to apply extension
`inputs`	object	-	Extension-specific configuration

Metadata Configuration

Metadata is a way to add additional information to the test run. It is a key-value pair that can be used to add additional information to the test run.

json

{
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}

Metadata Properties

It is a key-value pair that can be used to add additional information to the test run.

Property	Type	Required	Description
`environment`	string	No	Environment of the test run
`team`	string	No	Team of the test run
`data`	object	No	Data to be added to the test run

key (string) - Key of the data
value (string) - Value of the data

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
function

json

{
  "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.

json

{
  "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:

bash

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

Configuration Examples

Simple Slack Notification

json

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

Multi-Target with Conditions

json

{
  "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

json

{
  "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"]
    }
  ],
  "extensions": [
    {
      "name": "mentions",
      "condition": "fail",
      "inputs": {
        "users": ["[email protected]"],
        "teams": ["qa-team"]
      }
    },
    {
      "name": "hyperlinks",
      "inputs": {
        "links": [
          {
            "text": "View Build",
            "url": "${CI_PIPELINE_URL}"
          }
        ]
      }
    }
  ]
}

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

Configuration Reference ​

Configuration File ​

Top-Level Properties ​

Results Configuration ​

Result Properties ​

Supported Formats ​

Automation Test Results ​

Performance Test Results ​

Targets Configuration ​

Target Properties ​

Extensions Configuration ​

Extension Properties ​

Metadata Configuration ​

Metadata Properties ​

Conditions ​

Condition (Test Results) ​

Condition (Dynamic) ​

Condition (Function) ​

Command-Line Override ​

Configuration Examples ​

Simple Slack Notification ​

Multi-Target with Conditions ​

Complete Configuration ​

Related Documentation ​

Configuration Reference

Configuration File

Top-Level Properties

Results Configuration

Result Properties

Supported Formats

Automation Test Results

Performance Test Results

Targets Configuration

Target Properties

Extensions Configuration

Extension Properties

Metadata Configuration

Metadata Properties

Conditions

Condition (Test Results)

Condition (Dynamic)

Condition (Function)

Command-Line Override

Configuration Examples

Simple Slack Notification

Multi-Target with Conditions

Complete Configuration

Related Documentation