https://github.com/ctrf-io/slack-test-reporter
Send Slack notifications with test results from popular testing frameworks using a single command in your CI/CD
https://github.com/ctrf-io/slack-test-reporter
Last synced: 3 months ago
JSON representation
Send Slack notifications with test results from popular testing frameworks using a single command in your CI/CD
- Host: GitHub
- URL: https://github.com/ctrf-io/slack-test-reporter
- Owner: ctrf-io
- License: mit
- Created: 2024-05-30T22:06:17.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-16T18:21:28.000Z (4 months ago)
- Last Synced: 2025-04-02T03:55:02.884Z (4 months ago)
- Language: TypeScript
- Homepage: https://ctrf.io
- Size: 812 KB
- Stars: 28
- Watchers: 1
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Slack Test Results Notification
> Send Slack message with test results from popular testing frameworks
A Slack test reporting tool that supports all major testing frameworks.
Generate, publish and alert your team with detailed test results, including
summaries, in-depth reports, failed test analyses, flaky test detection and AI
analyses directly to your chosen Slack channel.
💚
CTRF tooling is open source and free to use
You can support the project with a follow and a star
Maintained by Matthew Thomas
Contributions are very welcome!
Explore more integrations
## Features
- **Send Test Results to Slack**: Automatically send test results to a Slack channel.
- **Send Flaky Test Details to Slack**: Automatically send flaky test details to a Slack channel.
- **Send AI Test Summary to Slack**: Automatically send AI test summary to a Slack channel.
- **Send Failed Test Details to Slack**: Automatically send failed test details to a Slack channel.
- **Build your own Slack message**: Create and customize your own Slack test reports with our flexible templating system.
- **Tagging**: Tag users, channels and groups in the message.
- **Conditional Notifications**: Use the `--onFailOnly` option to send notifications only if tests fail.
## Setup
You'll need a CTRF report generated by your testing framework. [CTRF reporters](https://github.com/orgs/ctrf-io/repositories) are available for most testing frameworks and easy to install.
**No CTRF reporter? No problem!**
Use [junit-to-ctrf](https://github.com/ctrf-io/junit-to-ctrf) to convert a JUnit report to CTRF.
### Create a Slack Incoming Webhook
1. Go to the [Slack API: Incoming Webhooks](https://api.slack.com/messaging/webhooks) page.
2. Click on "Create a Slack App" or use an existing app.
3. Add the "Incoming Webhooks" feature to your app.
4. Activate the Incoming Webhook and add a new webhook to your workspace.
5. Copy the webhook URL provided.
### Set the Environment Variable
Set the webhook URL as an environment variable in your shell or CI environment:
```sh
export SLACK_WEBHOOK_URL='https://hooks.slack.com/services/your/webhook/url'
```
Make sure to replace `'https://hooks.slack.com/services/your/webhook/url'` with your actual webhook URL.
You might want to store the webhook URL as a secret.
## Usage
You can use a glob pattern or a single file path to send the test results summary to Slack.
### Results
To send the test results summary to Slack:
```sh
npx slack-ctrf results /path/to/ctrf-report.json
```
You can use a glob pattern with multiple files which will be merged together:
```sh
npx slack-ctrf results "ctrf/*.json"
```
### AI Summary
To send AI failed test summary to Slack:
```sh
npx slack-ctrf ai /path/to/ctrf-report.json
```
Use `--consolidated` argumement to send a single message with all AI summaries
```sh
npx slack-ctrf ai /path/to/ctrf-report.json --consolidated
```
See the [AI Test Reporter](https://github.com/ctrf-io/ai-test-reporter) to add AI summaries to your CTRF report
### Flaky
To send flaky test report to Slack:
```sh
npx slack-ctrf flaky /path/to/ctrf-report.json
```
## Failed
To send failed test report to Slack:
```sh
npx slack-ctrf failed /path/to/ctrf-report.json
```
Use `--consolidated` argumement to send a single message with all AI summaries
```sh
npx slack-ctrf failed /path/to/ctrf-report.json --consolidated
```
## Build your own Slack message
The `custom` method lets you build your own report using a Handlebars
template allowing you to leverage data from your CTRF report to build a dynamic Slack message. The template can be a Block Kit JSON or Slack flavored markdown context block.
To send a message to Slack using a custom Handlebars template:
```sh
npx slack-ctrf custom /path/to/ctrf-report.json /path/to/template.hbs --blockkit
```
```sh
npx slack-ctrf custom /path/to/ctrf-report.json /path/to/template.hbs --markdown
```
The template has access to the entire CTRF report data through the `ctrf` variable. For example:
```handlebars
Tests: {{ctrf.summary.tests}}
```
```markdown
Tests: 100
```
### Block Kit JSON
Provide a Block Kit JSON template to the `--blockkit` option. See the [Slack Block Kit Documentation](https://api.slack.com/block-kit) and [Slack Block Kit Builder](https://api.slack.com/tools/block-kit-builder) for help creating a template.
The Block Kit JSON template can include Handlebars syntax to access test report data. For example:
```json
{
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Test Results: {{ctrf.summary.total}} tests run"
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Passed:* {{ctrf.summary.passed}}\n*Failed:* {{ctrf.summary.failed}}"
}
}
]
}
```
See the [templates](templates) directory for examples.
### Slack Flavored Markdown
Provide a Slack flavored markdown template to the `--markdown` option. See the [Slack Flavored Markdown Documentation](https://api.slack.com/block-kit) for help creating a template.
See the [templates](templates) directory for examples.
### Handlebars
Handlebars is a simple templating language that lets you insert data into your
message in a declarative way. You can use placeholders, conditionals, and loops
to dynamically generate content based on your test results.
## CTRF Properties
The `ctrf` object provides access to your test results data. Here are the common
properties:
### Summary (`ctrf.summary`)
- `tests`: Total number of tests
- `passed`: Number of passed tests
- `failed`: Number of failed tests
- `skipped`: Number of skipped tests
- `start`: Test suite start time
- `stop`: Test suite end time
### Individual Tests (`ctrf.tests`)
An array of test results, each containing:
- `name`: Test name
- `status`: Test status ("passed", "failed", "skipped")
- `message`: Test output/error message
- `duration`: Test duration in milliseconds
- `retries`: Number of retries (for flaky tests)
Example accessing test data:
```hbs
{{#each ctrf.tests}}
Test: {{this.name}} - Status: {{this.status}}
{{/each}}
```
### Helpers
The template can include helpers to format the data. See the [handlebars built-in helpers](https://handlebarsjs.com/guide/#helpers) and custom [helpers](src/handlebars/helpers) directory for the available helpers.
## Send Only on Failures
To send the test results summary to Slack only if there are failed tests, use the `--onFailOnly` option:
```sh
npx slack-ctrf results /path/to/ctrf-file.json --onFailOnly
```
or using the alias:
```sh
npx slack-ctrf results /path/to/ctrf-file.json -f
```
## Custom Notification Title
You can choose a custom title for your notification, use the `--title` option:
```sh
npx slack-ctrf results /path/to/ctrf-file.json --title "Custom Title"
```
or using the alias:
```sh
npx slack-ctrf results /path/to/ctrf-file.json -t "Custom Title"
```
## Add Prefix and Suffix
Add custom markdown text to as a prefix, or suffix to the message:
```sh
npx slack-ctrf results /path/to/ctrf-file.json -p "prefix" -s "suffix"
```
Read about compatible [markdown](https://api.slack.com/reference/surfaces/formatting#basic-formatting)
## Tagging a user, channel or group
You can tag users, channels or groups in the message by using the `--prefix` or `--suffix` options.
You need to a Slack user ID, channel ID or group ID.
You can find your user ID by:
- Clicking on your profile picture in Slack
- Clicking the three dots (...)
- Selecting "Copy member ID"
Once you have your user ID (which will look something like U01ABC123DE), use that in your command instead of your display name:
```sh
npx slack-ctrf results /path/to/ctrf-file.json -s "<@U0123456789> please review the results"
```
You can also tag a channel by using the `#` symbol with the channel ID:
```sh
npx slack-ctrf results /path/to/ctrf-file.json -s "<#C0123456789> please review the results"
```
And finally, you can tag a group by using the `\!subteam^` symbol with the group ID:
```sh
npx slack-ctrf results /path/to/ctrf-file.json -s "<\!subteam^0123456789> please review the results"
```
## Options
- `--onFailOnly, -f`: Send notification only if there are failed tests.
- `--title, -t`: Title of the notification.
- `--prefix, -p`: Custom markdown text to add as a prefix to the message
- `--suffix, -p`: Custom markdown text to add as a prefix to the message
## Merge reports
You can merge reports if your chosen reporter generates multiple reports through design, parallelisation or otherwise.
If you use a glob pattern, the reports will be merged automatically.
Otherwise, the [ctrf-cli](https://github.com/ctrf-io/ctrf-cli) package provides a method to merge multiple ctrf json files into a single file.
After executing your tests, use the following command:
```sh
npx ctrf merge
```
Replace directory with the path to the directory containing the CTRF reports you want to merge.
## Programmatic Usage
You can use the package programmatically to send notifications to Slack. To install the package, run:
```sh
npm install slack-ctrf
```
The package exports the following functions:
- `sendTestResultsToSlack`
- `sendFlakyResultsToSlack`
- `sendFailedResultsToSlack`
- `sendAISummaryToSlack`
- `sendCustomMarkdownTemplateToSlack`
- `sendCustomBlockKitTemplateToSlack`