Test your webhook

While developing your webhook, you may want to test it with real Business Messages payloads. Instead of manually creating tests, you can use the Business Messages test framework to test your webhook with various JSON payload types your webhook may receive in production.

To get started, all you need is a URL to a running instance of your webhook. The test framework is easy to install, and you can test your webhook with a single command.

Getting started

Install the framework

The easiest way to install the framework is with the NPM package manager. The framework is published in the NPM package registry, so you can install it with npm:

npm install -g bm-test-framework

Run the tests

With the package installed, you can supply your webhook URL as an environment variable and run all tests with the following command:

BMTF_ENDPOINT_URL=<Your webhook URL> bm-test-framework

The test framework's results looks like this:

  Sending payloads to <Your webhook URL>
      ✔ authentication-request.json should return 200
      ✔ event-receive.json should return 200
      ✔ image-message.json should return 200 (862ms)
      ✔ read-receipt.json should return 200
      ✔ suggestion-message.json should return 200
      ✔ text-message.json should return 200 (134ms)
      ✔ text-with-dialogflow-response.json should return 200 (128ms)
      ✔ user-receipt.json should return 200

In this example test run, all of the test cases passed.

If your webhook fails on one of the test cases, it means your webhook does not respond with a 200 OK to that test case's JSON payload. In that case, the test framework prints error information to help you debug. See the test framework README to learn more about specific test cases.

Use the framework in your NodeJS project

To use the framework from within your own code in a NodeJS project, or from within a Mocha test suite, first install the package as a development dependency:

npm install --save-dev bm-test-framework

Once installed, you can create a BmTestFramework object to manage the tests:

const BmTestFramework = require('bm-test-framework');
const bmTestFramework = new BmTestFramework({endpointURL: <Your webhook URL>});

The payloads member array contains all the test cases. You can use the sendPayload method to run a specific test. For example, the following code runs the first test in the framework:

bmTestFramework.sendPayload(bmTestFramework.payloads[0])

Configure the tests

In addition to the required BMTF_ENDPOINT_URL environment variable, you can also set optional environment variables to customize the test behavior:

Environment variable	Config field name	Type	Description
BMTF_RANDOM_UUID	randomUuid	boolean	If true, sets the conversation ID to a randomized UUID with a valid format. If false, sets all conversation IDs to "CONVERSATION-ID".
BMTF_TIMEOUT	timeout	Number or formatted time string	Sets the timeout in milliseconds for each test case. The default timeout is 2000ms for each test case. See the Mocha API reference for detailed type and formatting specifications.

For example, the following code runs the test framework from the command line with the random UUID option enabled and with a timeout of 1000ms:

BMTF_ENDPOINT_URL=<Your webhook URL> BMTF_TIMEOUT=1000 BMTF_RANDOM_UUID=true bm-test-framework

To customize the test behavior in your NodeJS project, you can also pass the same variables into the config object when you create your BmTestFramework:

const bmTestFramework = new BmTestFramework({endpointURL: <Your webhook URL>, randomUuid: true, timeout: 1000});