Documentation Grafana Cloud Testing and synthetics Performance testing Author and run tests Send notifications

Send notifications

It would be tedious to monitor every test in your ongoing test operations. Instead, you can configure sending notifications whenever a significant test event happens. For example, you could send a notification whenever a test unexpectedly aborts or fails a check or threshold.

k6 supports the following ways to send notifications:

• To a third-party platform, like workspaces for Slack and Microsoft teams
• Through a custom webhooks
• Through email

When you schedule a test or add it to your continuous integration pipeline, you’ll likely want to configure a notification for failed events, thus automating test execution and observation.

Before you begin

• You must be a Grafana Owner or Admin to set up notifications.

Add a Slack notification

To send notifications to Slack, follow these steps.

1. From Slack, add a Custom Integration and select Incoming WebHook app.
2. Select or create a channel and copy Slack’s generated WebHook URL.

In Grafana Cloud:

1. Log in to your Grafana Cloud account.
2. Go to Testing & synthetics > Performance > Settings.
3. Under Integrations, click Notifications.
4. Click Setup under the Slack field, or click Create new notification and select Slack.
5. Give your notification a name under Notification name. That can help differentiate between multiple Slack integrations.
6. Paste the Slack Webhook URL into the URL field.
7. From the Notification events dropdown, select the events you want to trigger notifications. Refer to the supported notification events.
8. Save.

If you click on the Edit icon next to the notification you just created, you can see a Send test notification button. Use that to send a test message to make sure the notification is set up correctly.

With Advanced mode, you can view and customize exactly what Grafana Cloud sends to Slack. Read more about it in the Custom webhook section below.

Add a Microsoft Teams notification

First, figure out the webhook URL for your Microsoft Team setup.

In Grafana Cloud:

1. Log in to your Grafana Cloud account.
2. Go to Testing & synthetics > Performance > Settings.
3. Under Integrations, click Notifications.
4. Click Setup under the Microsoft Teams field, or click Create new notification and select Microsoft Teams.
5. Give your notification a name under Notification name. That can help differentiate between multiple Microsoft Teams integrations.
6. Paste the Microsoft Teams Webhook URL into the URL field.
7. From the Notification events dropdown, select the events you want to trigger notifications. Refer to the supported notification events.
8. Save.

If you click on the Edit icon next to the notification you just created, you can see a Send test notification button. Use that to send a test message to make sure the notification is set up correctly.

With Advanced mode, you can view and customize exactly what Grafana Cloud sends to Microsoft Teams. Read more about it in the Custom webhook section below.

Add a Custom Webhook

While Grafana Cloud offers defaults for Slack and Microsoft Teams, you can send a webhook to any third-party service with a custom webhook integration. You can customize the JSON payload directly in Grafana Cloud.

First, get the webhook URL of your service of choice. If experimenting, you can try a free online service that provides temporary URLs for webhook debugging, like webhook.site.

In Grafana Cloud:

1. Log in to your Grafana Cloud account.
2. Go to Testing & synthetics > Performance > Settings.
3. Under Integrations, click Notifications.
4. Click Setup under the Custom Webhook field, or click Create new notification and select Custom Webhook.
5. Give your notification a name under Notification name. That can help differentiate between multiple Custom Webhook integrations.
6. Paste the Custom Webhook URL into the URL field.
7. From the Notification events dropdown, select the events you want to trigger notifications. Refer to the supported notification events.
8. The generic template showcases all the possible values k6 can send. Modify the JSON payload as needed. Refer to Template context variables.
9. Save.

After you save, select the notification you just created, and test your webhook with the Send test notification. Grafana Cloud fills all the context fields in your template with mock values. You can fix any errors reported by sending the test event, while checking that each field’s value is what you expect.

Add a Custom Email notification

Instead of using webhooks, you can have Grafana Cloud send you an email. First, decide which email addresses will receive the notification.

In Grafana Cloud:

1. Log in to your Grafana Cloud account.
2. Go to Testing & synthetics > Performance > Settings.
3. Under Integrations, click Notifications.
4. Click Setup under the Email field, or click Create new notification and select Email.
5. Give your notification a name under Notification name. That can help differentiate between multiple Email integrations.
6. Enter an email subject under Subject. This helps filter and organize notifications in your email program.
7. In the Recipients field, select your organization’s member emails from the dropdown, or enter the email addresses that should receive the notification. Use commas or spaces to separate emails.
8. From the Notification events dropdown, select the events you want to trigger notifications. Refer to the supported notification events.
9. Optionally, toggle Advanced mode to edit the email notification that gets sent.
10. Save.

After you save, select the notification you just created, and test your webhook with the Send test notification. Grafana Cloud fills all the context fields in your template with mock values. You can fix any errors reported by sending the test event, while checking that each field’s value is what you expect.

Supported Notification events

Broadly, two types of events trigger notifications:

• When a test run starts
• When a test run ends

Within these categories, you can granularly configure which events trigger notifications.

Events when a test starts

Events when a test ends

You can safely pick multiple options and get at most get two notifications per test-run, one when it starts and one when it ends. k6 passes the event identifier along to specify which condition triggered the notification.

Templating syntax

The notification templates use the Jinja2 templating language. Jinja uses {{ }} to mark places in the template that will be replaced by actual values when the notification is created.

For example, let’s say we want to include the test name and identifier in our context.

From the Template Context list, note that these variables are accessed as test.name and test.id. Here’s what we need to add to the template:

JSON Copy

{
  ...
    "name": "{{ test.name }}",
    "test_run_id": {{ test.id }},
  ...
}

Jinja also supports simple if/else conditionals. Write conditionals in the form:

JSON Copy

{% if condition %}if_true_result{% else %}if_untrue_result{% endif %}

Here is an example (from the generic template) of setting a color based on the result of the test-run:

JSON Copy

{
    ...
    "color": "{% if test.result == 1 %}red{% else %}green{% endif %}",
    ...
}

Jinja also allows for for-loops.

JSON Copy

{% for value in iterable}
    ...
{% endfor %}

This example loops over the list of errors (if any):

JSON Copy

"errors": [
      {% for error in errors %}
        {
          "code": {{error.code}},
          "error_created": "{{error.created}}",
          "error_detail": "{{error.detail}}"
        }{{"," if not loop.last}}
      {% endfor %}
  ]

The loop.last is a special Jinja feature. Here it used in place of a comma after the last item (a comma at the end would not be valid JSON).

Remember that after the Jinja-parsing/replacing, the result must be a valid JSON structure. So in the examples above, note how we can leave the test.id as-is (since it’s an int), but because the test.name is a string, it must be enclosed in quotes " ... ". In the same way, the for-loop output must be created inside [ ... ] to have the result be a proper JSON array.

Template Context variables

You can use these variables in your notification templates.

To access them as expressions, use the default {{ }} delimiters. Note the type of each value and especially remember to put double quotes around strings, so the result after template-replacement is still valid JSON.

test

This holds test-run data for the test run that triggered the event.

user

Information about the user associated with this test-run.

event

Details about the event itself.

errors

An array of error objects attached to this test run (if any).

If looping over this array (let’s call the loop variable error), each item in the list has the following properties:

Notification message format

When an event is triggered, the cloud service sends a POST request to the configured URL.

Headers sent with all requests:

Header Example:

JSON Copy

X-k6cloud-ID: 19c5d426-3b4d-43c3-8277-37ad7d457430
X-k6cloud-Event: test.started
User-Agent: K6CloudWebHook

The body of the request is a JSON structure created by populating the chosen notification template with values relevant to the event.