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

Multiple reports in one file

Instead of a single configuration object at the root, you may use a reports array. Each element has the same shape as a normal config: results, optional targets, extensions, api_key, project, run, and so on. TestBeats runs publish once per entry (see the publish command implementation).

json

{
  "reports": [
    {
      "results": [{ "type": "junit", "files": ["**/a.xml"] }],
      "targets": [{ "name": "slack", "inputs": { "url": "{SLACK_A}" } }]
    },
    {
      "results": [{ "type": "junit", "files": ["**/b.xml"] }],
      "targets": [{ "name": "teams", "inputs": { "url": "{TEAMS_B}" } }]
    }
  ]
}

Results Configuration

Define where TestBeats should find test results, or supply an already-built result object:

json

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

Result properties

Property	Type	Required	Description
`type`	string	Yes	Result format (see below)
`files`	array	Yes for file-based types	Glob patterns or paths (not used for `custom`)
`result`	object	Yes for `custom`	Inline test result object (same structure TestBeats uses after parsing)

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

Custom (inline) results

Use type: "custom" when you already have a parsed result object (for example from your own pipeline or the test-results-parser package). Provide result and omit files:

json

{
  "type": "custom",
  "result": {
    "name": "My suite",
    "total": 0,
    "passed": 0,
    "failed": 0,
    "errors": 0,
    "skipped": 0,
    "retried": 0,
    "duration": 0,
    "status": "PASS",
    "tags": [],
    "metadata": {},
    "suites": []
  }
}

The object should follow the same shape TestBeats uses after parsing (including suites, cases, counters, tags, and metadata as needed).

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

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 ​

Multiple reports in one file ​

Results Configuration ​

Result properties ​

Supported formats ​

Automation test results ​

Performance test results ​

Custom (inline) 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

Multiple reports in one file

Results Configuration

Result properties

Supported formats

Automation test results

Performance test results

Custom (inline) 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