# mulesoft API Functional Monitoring - Full Documentation

<!-- document id=8c5179261205d8da1d49302f5bbd6d1a855c435ead1e5ed360f2ab8c7a06730f url=/mulesoft/current/en-us/api-functional-monitoring/afm-add-schedule.md -->

---
product: API Functional Monitoring
---

# Adding Schedules

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can add a schedule to an existing monitor if either of the following two conditions is true:

- You plan to run the test associated with the schedule in a public location, and the allocation of
  schedules for your Anypoint Platform organization is not exhausted.

- You plan to run the test associated with the schedule in a private location.

## Before You Begin

Ensure that you have the following permission set in Access Management:

- **Exchange > Exchange Administrator** or **Exchange > Exchange Contributor**

An Anypoint Platform administrator for your organization grants permission. See
[Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions).

## Add a Schedule

1.  Select the monitor in which you want to add a schedule.

2.  Click **Add Schedule** from the **Schedules** table.

3.  In the **Add Schedule** dialog box, select the following:

    - The location in which to run the test

    - The monitor schedule interval and its required information:

      <table><colgroup><col> <col> <col></colgroup><thead><tr><th>Interval</th><th>Required Information</th><th>Definition</th></tr></thead><tbody><tr><td><p>Hourly</p></td><td><p>The minute</p></td><td><p>The minute at which the test begins, starting 60 minutes after you create the schedule</p></td></tr><tr><td><p>Daily</p></td><td><p>The time of each day</p></td><td><p>The time each day (hour and minutes) at which the test begins</p></td></tr><tr><td><p>Weekly</p></td><td><p>Day of the week and time of day</p></td><td><p>The day of the week and the time of that day that initiates the test</p></td></tr><tr><td><p>Monthly</p></td><td><p>Day of the month and time of day</p></td><td><p>The day of the month and the time of that day that initiates the test</p></td></tr><tr><td><p>Advanced</p></td><td><p>Cron</p></td><td><p>The cron expression for the frequency of the test.</p></td></tr></tbody></table>

4.  Set **Configuration**.

5.  Click **Add**.

    The countdown to the first run of the selected test begins.

> [!NOTE] Specified test times correspond with your time zone.

## Limits for Schedule Intervals by Location

The minimum interval for schedules that run in private locations is always five minutes.

The minimum interval for schedules that run in public locations depends on the number of schedule
entitlements, or API monitor entitlements, that you have. If you have more than five, the limit is
five minutes. Otherwise, it is fifteen minutes.

The limit depends on the type of location, not on whether the API is public or private, because you
can test a public API from a private location.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Location Type</th><th>Number of Entitlements</th><th>Account Type</th><th>Interval Time Allowed</th></tr></thead><tbody><tr><td><p>Public</p></td><td><p>5 or less</p></td><td><p>Developer</p></td><td><p>15 minutes</p></td></tr><tr><td><p>Public</p></td><td><p>5 or less</p></td><td><p>Other</p></td><td><p>15 minutes</p></td></tr><tr><td><p>Public</p></td><td><p>More than 5</p></td><td><p>Developer</p></td><td><p>15 minutes</p></td></tr><tr><td><p>Public</p></td><td><p>More than 5</p></td><td><p>Other</p></td><td><p>5 minutes</p></td></tr><tr><td><p>Private</p></td><td><p>Any number</p></td><td><p>N/A</p></td><td><p>5 minutes</p></td></tr></tbody></table>

## Scheduling Long-Running Tests

Tests for a monitor that are run in public locations silently fail when the run time exceeds 120
seconds. If you need longer tests, the best solution is to use a private location, because you can
run tests that have a long duration in private locations.

If you want to run longer-running tests in a public location, you can:

1.  Download the monitor and split the tests across multiple monitors using the BAT CLI.

2.  Run and time each test to ensure that their running times are under 120 seconds.

3.  Upload the tests as separate monitors to run in the web UI or run them through BAT CLI.

## See Also

- [Differences in the Monitoring of Public and Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-public-apis)

- [Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions)

<!-- document id=08ab599c0407805fe8a792145c47fa1d9a309590e15a8cb4f0e7255648e5006b url=/mulesoft/current/en-us/api-functional-monitoring/afm-in-anypoint-platform.md -->

---
product: API Functional Monitoring
---

# API Functional Monitoring in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Functional Monitoring enables you to monitor responses to requests sent to API resources at
their endpoints. You monitor APIs by accessing the **Functional Monitoring** section of Anypoint
Monitoring, which you select from the home page of Anypoint Platform.

The **Functional Monitoring** section contains tools for creating and editing monitors.
Additionally, you can upload custom test suites written in BAT, a Behavior Driven Development (BDD)
language.

The following image illustrates the components of a monitor:

![afm ui overview a new](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-overview-a-new.png)

A monitor includes a test and one or more schedules for running tests.

A monitor test includes the following:

- The endpoints to verify

- Optional assertions to verify at the endpoints (for example, a 200 status code)

- Optional HTTP headers to include when sending requests to the endpoints

- Optional tools, such as SumoLogic and Slack, used to send test reports

A monitor test schedule includes the following:

- The location from which to run the test

  Locations can be public or private. For details, see
  [Monitoring the Endpoints of Public APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-public-apis) and
  [Monitoring the Endpoints of Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-private-apis).

- The time interval between tests

The Functional Monitoring page with a monitor selected is shown in the following image:

![AFM page showing a selected monitor’s details](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-test-versions-and-schedules-new.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Duration of the test for the selected monitor.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Daily average response time in milliseconds of all tests to all endpoints. The colors in each bar indicate the breakdown of the average time for each of the steps in a test. Hover over the bar to see the breakdown details.</td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>Schedule information, including when the next run is scheduled, the schedule interval, and information about the location where the tests are scheduled to run.</td></tr><tr><td><i data-value="4"></i><b>4</b></td><td>Details about the previous execution, including the method executed and the assertions.</td></tr><tr><td><i data-value="5"></i><b>5</b></td><td>A summary list of the last few executions.</td></tr><tr><td><i data-value="6"></i><b>6</b></td><td>Option to add schedules to the selected monitor.</td></tr></tbody></table>

The bar graph shows the daily average response time in milliseconds of all tests to all endpoints.
The colors in each bar indicate the average time for each of the steps in a test. Hover over the bar
to see the details.

## See Also

- [Creating Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor)

- [Uploading Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-upload-monitor)

<!-- document id=3d5c7839b69a91a5864286a3d1fcaf0a47ec45619301a8a20a4de884017c5388 url=/mulesoft/current/en-us/api-functional-monitoring/index.md -->

---
product: API Functional Monitoring
---

# API Functional Monitoring Overview

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Functional Monitoring is a component of Anypoint Platform that enables you to ensure the quality
and reliability of public and private APIs that are being used in application networks.

Developers and operators can use API Functional Monitoring to perform consistent testing of the
functional behavior and performance of APIs throughout the API lifecycle, in testing and production
environments. You can:

- Monitor Public or Private APIs from the Anypoint Monitoring UI or by using the BAT command line
  interface (BAT CLI)

- View and report on the results of monitor executions

The Functional Monitoring page with a monitor selected is shown in the following image:

![AFM page showing a selected monitor’s details](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-test-versions-and-schedules-new.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Duration of the test for the selected monitor.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Daily average response time in milliseconds of all tests to all endpoints. The colors in each bar indicate the breakdown of the average time for each of the steps in a test. Hover over the bar to see the breakdown details.</td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>Schedule information, including when the next run is scheduled, the schedule interval, and information about the location where the tests are scheduled to run.</td></tr><tr><td><i data-value="4"></i><b>4</b></td><td>Details about the previous execution, including the method executed and the assertions.</td></tr><tr><td><i data-value="5"></i><b>5</b></td><td>A summary list of the last few executions.</td></tr><tr><td><i data-value="6"></i><b>6</b></td><td>Option to add schedules to the selected monitor.</td></tr></tbody></table>

## Functional Monitoring Concepts

Following are the concepts you need to know to use API Functional Monitoring.

### Monitors

A monitor is a repeating schedule of one or more tests. Monitors are also called test suites.

### Tests

Tests run in monitors on a defined schedule. Test cases are defined using Behavior Driven
Development (BDD) language, a common, declarative, and easy-to-use behavior-description language.

### Behavior Driven Development (BDD) Language

The BDD language is used to write tests. It is based on DataWeave and follows the “given-when-then”
approach to describe behavior in terms of conditions and expected outcomes.

### Test Suites

See [Monitors](#afm-monitors).

### Schedules

Schedules are designated intervals and durations configured in monitors for test suites to run.

### Black Box Testing

Black box testing validates the overall behavior of an API and its live dependencies as a whole,
based entirely on inputs and outputs. These tests are done without knowing or altering the API
internals &mdash and without simulation or mocking.

### White Box Testing

White box testing validates the behavior of individual APIs against the understanding of how their
internals work. As part of this type of testing, you mock and simulate dependencies, such as
back-end systems and other APIs.

### Runtime Monitoring

Runtime monitoring ensures that deployed APIs operate within the expected performance level in
production environments. Runtime monitoring uses behavioral test cases with real inputs, expected
outputs, and live dependencies.

### Private APIs

Private APIs are APIs with endpoints that are accessible only within your network inside an Anypoint
VPC.

### Public APIs

Public APIs are APIs with endpoints that are exposed to the public internet. Tests of such endpoints
are run by workers that themselves run in public locations or private locations.

### Private Locations

A private location is a Mule application that runs in an environment in CloudHub 1.0 or Cloudhub
2.0. You can run tests against APIs that are accessible only within the private location. The
private location environment might have an Anypoint VPC associated with it. You can create multiple
private locations in a single instance of Anypoint VPC.

### Public Locations

A public location is a region, or resource pool, that is shared with other MuleSoft customers.
Examples of such regions are `us-east-1`, `us-east-2`, and `eu-central-1`.

## Next Steps

Continue to [Getting Started with API Functional Monitoring](https://docs.mulesoft.com/api-functional-monitoring/afm-getting-started).

## See Also

- [API Functional Monitoring in Anypoint Platform](https://docs.mulesoft.com/api-functional-monitoring/afm-in-anypoint-platform)

- [API Functional Monitoring with the BAT CLI](https://docs.mulesoft.com/api-functional-monitoring/bat-top)

<!-- document id=b2566b2c0976069f4ae14122dd418da13f0b24c74f3afd9b77da38b59e77cb87 url=/mulesoft/current/en-us/api-functional-monitoring/api-functional-monitoring-release-notes.md -->

---
product: API Functional Monitoring
---

# API Functional Monitoring Release Notes

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following release notes are provided for API Functional Monitoring:

- [API Functional Monitoring (AFM) Release Notes](https://docs.mulesoft.com/release-notes/api-functional-monitoring/api-functional-monitoring-release-notes)

## See Also

- [API Functional Monitoring Overview](https://docs.mulesoft.com/api-functional-monitoring/)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=f347656764c794c3eed5a285009382327dc05be7a40ebc20ab2fe36d31bbfc1b url=/mulesoft/current/en-us/api-functional-monitoring/bat-top.md -->

---
product: API Functional Monitoring
---

# API Functional Monitoring with the Blackbox Automated Testing (BAT) CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use API Functional Monitoring to run a test or suite of tests on an API. API Functional
Monitoring is based on Blackbox Automated Testing (BAT).

Using API Functional Monitoring, you can automate testing and get test reports. You can test before
pushing code into your repository and before deploying to production. Tests can verify API
functionality and validate results the API generates. You can monitor APIs at each stage of the
software development life cycle and in production.

The prerequisites for testing and scheduling are:

- One or more deployed APIs

- Installation of BAT.

- A directory that contains a test suite.

- At least one test file in that directory.

  You write tests in Behavior Driven Development (BDD) syntax using a code or text editor, such as
  IntelliJ. Test files must use the `.dwl` extension for processing by DataWeave.

An additional prerequisite, this one for monitoring scheduled tests in the cloud, is an account on
Anypoint Platform.

## See Also

- [Install BAT](https://docs.mulesoft.com/api-functional-monitoring/bat-install-task)

- [BDD Test Writing Language Reference](https://docs.mulesoft.com/api-functional-monitoring/bat-bdd-reference)

<!-- document id=5ddb36be8699a6f5a156f2b8360441d6b622a66275c1a779a737d63321ee71b8 url=/mulesoft/current/en-us/api-functional-monitoring/bat-command-reference.md -->

---
product: API Functional Monitoring
---

# BAT CLI Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

BAT CLI provides an API Functional Monitoring command line interface through an integration with
Anypoint Platform. The command line interface lets you run tests locally and schedule monitors for
continuous API testing. You can schedule tests in the cloud using the CLI-xAPI.

This reference covers the syntax and key options you can use with the `bat` commands. Using the
`bat` commands, you can debug and run tests, get credentials for scheduling tests, schedule tests,
list test schedules, and perform additional operations.

For commands to execute successfully, the account under which BAT CLI logs in must have the required
permissions for the action the command is executing.

## Permissions Required

To use all of the `bat` commands to execute the corresponding actions in Anypoint Platform, you must
have the following permissions.

<table><colgroup><col> <col></colgroup><thead><tr><th>Permission</th><th>Actions</th></tr></thead><tbody><tr><td><p>Create Applications (Runtime Manager)</p></td><td><p>Create private locations</p></td></tr><tr><td><p>Delete Applications (Runtime Manager)</p></td><td><p>Delete private locations</p></td></tr><tr><td><p>Manage Settings (Runtime Manager)</p></td><td><p>Update private locations</p></td></tr><tr><td><p>View Environment</p></td><td><p>Log in using BAT CLI</p></td></tr><tr><td><p>View Organization</p></td><td><p>Use Secrets Manager through BAT CLI</p></td></tr><tr><td><p>Exchange Contributor (Exchange)</p></td><td><p>Create or modify a monitor; add or modify a schedule</p></td></tr><tr><td><p>Exchange Administrator (Exchange)</p></td><td><p>Create, modify, or delete a monitor; add, modify, or delete a schedule</p></td></tr></tbody><tfoot><tr><td><p>Grant access to secrets (Secrets Manager)</p></td><td><p>Use Secrets Manager</p></td></tr></tfoot></table>

## Login Options

To use the `bat` commands to execute API Functional Monitoring actions, you must first log in using
one of the following login methods.

### Login Using Connected Apps

`bat [login --client-id --client-secret [--profile=<value>] --host=<value>]`

This option logs in to an Anypoint Platform account using the client ID and client secret from a
connected app. This provides an alternative way to log in using MFA (multi-factor authentication) so
that a second factor is not required. MFA is now required for non-SSO accounts unless they are on
your organization’s exemption list. For information about connected apps, which are configured by
organization administrators, see [Connected Apps](https://docs.mulesoft.com/access-management/connected-apps-overview).

### Login Using a Username and Password

`bat [login --username=<value> [--profile=<value>] --host=<value>]`

This option logs in to an Anypoint Platform account using a username and password. It displays an
interactive command for the password.

`password for user [username]: <password>`

You can include the option `--password=<password>` in the `login` command.

## Execute Commands Stored in a File

`bat [<file> …​ | <option> …​]`

Where:

- `file` is the relative path to the path and file name.

  The file must have one of the following base names and one of the following extensions:

  - base file names: main, bat

  - extensions: .yaml, or .yml

    When you execute bat without any arguments, BAT reads the YAML in the current directory and runs
    the specified tests. You can create a `config` folder and add different configuration files in
    `config` for the environments.

- `bat ~/path/to/folder/`  
  Executes from the desired folder. BAT searches for and executes the `bat.yaml` and `main.dwl`
  files.

- `bat ./folder/file.dwl`  
  Executes using the desired file. The root of the project is the current folder. The root of the
  project is used to resolve imports and load libraries and files.

## `bat` Command Options

- `--help`

  Displays information about how to use the command.

- `--validate | -V`

  Validates the file or folder. Also works with `--config` to validate specific configurations.

- `--config=<name>`

  Selects a configuration file (from the `config` folder) and registers the result as a global
  variable.

- `--version`

  Prints to standard output the version numbers of installed BAT and wrapper. If the latest version
  is not installed, that version is downloaded.

- `--update`

  Updates the BAT CLI to the latest version and configures a `.bat-version` file in the current
  folder. The program always respects the `.bat-version` configuration when running tests. If the
  specified version is not installed, it is downloaded and installed before execution.

- `--debug`

  Sends troubleshooting information to standard output during an execution.

- `--track`

  Sends data from the local executions.

- `--bat-version=<version>`

  Executes BAT using the specified version.

- `--init-folder`

  Stores the files `exchange.json` and `main.dwl`, which you generate when you create a monitor in
  the current directory. Optional.

- `--init`

  Same as the `bat init` command, which sets up a basic project folder. The folder contains the
  following files:

  . ├── bat.yaml ├── config │   ├── default.dwl │   ├── devx.dwl │   ├── qax.dwl │   └── stgx.dwl
  └── tests └── HelloWorld.dwl

- `--password=<value>`

  The value is the password for the Anypoint Platform user name. If is not present, the value of the
  environment variable ANYPOINT\_PASSWORD is used. If a value for this variable is not set, the
  default password from credentials file is used.

- `--profile=<value>`

  Profile is:

  - The name of a profile for accessing an Anypoint Platform location and retaining the login
    information between BAT sessions. Using this option eliminates the need to relogin between
    sessions. Optional.

  - The name of a profile for scheduling a test that can be different from the BAT login profile you
    used. By default, BAT uses the login profile for scheduling. Optional.

  - If it is not present, the value of the environment variable ANYPOINT\_PROFILE is used. If a
    value for this variable is not set, the default profile is used.

- `--username=<value>`

  The value is an Anypoint Platform user name. If it is not present, the value of the environment
  variable ANYPOINT\_USERNAME is used. If a value for this variable is not set, the default username
  from the credentials file is used.

- `--useProxy`

  Use this option with each `bat` command if your system requires that you access Anypoint Platform
  through a proxy.

- `--client-id`

  The client ID from your connected app. You must use this option with the login command if you log
  in using a connected app.

- `--client-secret`

  The client secret from your connected app. You must use this option with the login command if you
  log in using a connected app.

## `bat` Commands

You can use the following `bat` commands to manage cloud integration and to schedule and configure
tests and monitors using Anypoint Platform.

- `init`

  Sets up a basic project folder with config files, HelloWorld basic test, and a yaml descriptor
  file.

- `schedule ls | list`

  List all of the schedules that exist in the given profile’s organization.

- `schedule create [--cron="<expression>"] [--location=<id>]`

  Create a scheduler using a cron expression and generating a ZIP file that includes the tests and
  all the files. If you do not enter a cron expression, tests are scheduled to run every 15 minutes.

- `schedule endpoint <monitor-URL> [--cron="<expression>"] [--name=<suiteName>] [--location=<id>] [--new-relic-license-key=<newRelicLicenseKey>] [--slack-webhook=<slackWebHook>] [--email-list=<emails>] [--sumo-logic-endpoint=<sumoLogicEndpoint>] [--pager-duty-routing-key=<pagerDutyRoutingKey>] [--custom-report-url=<customReportUrl>] [--custom-report-headers=<header1,header2,…​,headerN>] [--custom-report-transformation=<pathToDwlFile>][--init-folder] [--status-code=<code>]`

  Create a monitor in Exchange using a URL, such as the following example URL: `http://example.com`.
  Optionally, you can add options to generate the `bat.yaml` with different parameters.

  - `[--cron="<expression>"]` By default, tests are scheduled to run every 15 minutes. You can
    change with the cron expression.

  - `[--name="<suiteName>"]` To set the name of the suite.

  - `[--location="<id>"]` Set a specific location ID to the monitor.

  - `[--new-relic-license-key="<newRelicLicenseKey>"]` Add the New Relic report to the bat.yaml.

  - `[--slack-webhook="<slackWebHook>"]` Add the Slack report to the bat.yaml.

  - `[--sumo-logic-endpoint="<sumoLogicEndpoint>"]` Add the Sumo Logic report to the bat.yaml.

  - `[--pager-duty-routing-key="<pagerDutyRoutingKey>"]` Add the PagerDuty report to the bat.yaml.

  - `[--custom-report-url="<customReportUrl>"] [--custom-report-headers="<header1,header2,…​,headerN>"] | [--custom-report-transformation="<pathToDwlFile>"]`
    Add the custom report to the bat.yaml file and optionally you can add the transformation file.

  - `[--init-folder]` Store generated exchange.json, bat.yaml and main.dml in the current directory.

  - `[--status-code=<code>]` Use code as HTTP code for test templates.

- `schedule rm | remove <id>`

  Deletes a schedule by its ID.

- `schedule disable <id>` Disables the schedule that is identified by the specified ID.

- `schedule enable <id>`

  Enables the schedule that is identified by the specified ID. Use this command only when you want
  to enable a schedule that you have disabled with the `bat schedule disable <id>` command.

- `whoami`

  Prints basic user information to standard output. Other profiles can be used with the `--profile`
  option.

- `worker register [--name=<value>]`

  Generates a post with the machine name and create a dummy target.

- `worker unregister [--name=<value>]`

  Unregisters worker.

- `worker id`

  Gets worker ID.

- `location create <name>`

  Creates a private location in the given profile’s organization in Anypoint Platform. See
  [Monitoring the Endpoints of Public APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-public-apis) and
  [Monitoring the Endpoints of Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-private-apis) for more information about
  private and public locations.

- `location delete <id>`

  Deletes a private location from the list of private locations in the given profile’s organization
  in Anypoint Platform.

  `id`

  Specify the ID that identifies the location. You can obtain the ID by running the
  `bat location ls` command.

- `location ls|list`

  Lists the private and public locations that exist in the given profile’s organization in Anypoint
  Platform. This command replaces `target ls|list`.

- `location update <id>`

  Updates a location by its ID. If a new version of the worker available, updates the location using
  latest version. This option is valid only for Mule locations.

- `get_token`

  Returns the token for accessing Anypoint Platform in the credentials file. Requires that you first
  run `bat login` to generate a profile.

- `grant`

  Grants API Functional Monitoring permission to access a shared secret that is stored in Anypoint
  Secrets Manager. You must grant API Functional Monitoring permission to access any shared secret
  that you use in a test or to access a reporter.

  Run the `bat grant` command before configuring a test or a reporter to use a shared secret. The
  aliases that you create in the command are what you specify in tests and configurations for
  reporters.

  bat grant -g=MySecretGroupName
  -s=MyAlias1:MySecretName1,MyAlias2:MySecretName2,…,MyAliasN:MySecretNameN \[--forceUpdate\]

  \-g

  Specify the name of the group in Anypoint Secrets Manager in which the shared secret is stored.

  \-s

  Specify an alias, a colon, and the name of the shared secret. The alias can be any combination of
  alphanumeric characters. The name of the shared secret is the name that identifies the shared
  secret in the group. If you want to use a single command to grant the BAT CLI permission to use
  more than one shared secret from the same group, separate each `alias:name` pair with a comma.
  +The secret must be created in a secrets group that is in the same environment that you are using
  in the BAT CLI. To find out which environment you are using in the BAT CLI, run the command
  `bat whoami`. The output contains the ID for the environment. Run the command `bat environment ls`
  to list the environments that you have access to. Match the ID from the `bat whoami` command with
  one of the environments listed. If you need to switch to the environment that your secrets group
  is in, run the command bat environment switch name, where name is the name of the environment.

  \--forceUpdate

  Specify this option if API Functional Monitoring lost access to a shared secret and you need to
  grant access again.

- `execution ls|list`

  Lists the monitors that are running for the specified profile. If no profile is specified, the
  default profile is used. The monitors listed are all of those in the current environment and for
  the current profile that were written and started through the BAT CLI, and any that were created
  online in Anypoint Platform.

  The output looks like this:

  Last executions:

      daily-retail-test:1.0.1                  PASSED     10 seconds ago
      internal-run-api-check:1.0.0             PASSED     11 minutes ago

- `environment ls|list`

- `environment switch <name>`

  The two options `ls` and `list` list the environments that are available for the specified
  profile. If no profile is specified, the default profile is used.

  The `switch` option enables you to use one of the listed environments. Add the name of the
  environment to the end of the command, as in this example that uses the environment `Sandbox`:

  bat environment switch Sandbox

## BAT Command Examples

- Run multiple test files from the bat.yaml file.

  `bat bat.yaml`

- Run a single file.

  `bat ./test/myFile.dwl`

- Determine the installed version.

  `bat --version`

  Example output if you do not have the latest version is:

  Updating Version: You have an older BAT version. The new version is downloaded in
  /Users/<username>/.bat/bat-cli-1.0.51 Downloading version 1.0.51. Please
  wait\`....................... BAT Wrapper: 1.0.53 BAT Version: 1.0.51

## See Also

- [Scheduling Testing and Monitoring](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-test-task)

- [Using Secrets to Mask Sensitive Information in Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-mask-info-in-monitors)

<!-- document id=eda0b5c35c873a96fa94ea29aa88193fe122f27c7f529577bae08673ee562865 url=/mulesoft/current/en-us/api-functional-monitoring/bat-bdd-reference.md -->

---
product: API Functional Monitoring
---

# BDD Test-Writing Syntax Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Behavior Driven Development (BDD) is the syntax for writing BAT tests for processing in DataWeave.
BDD is an embedded domain specific language (EDSL) that resembles other testing frameworks, such as
Mocha and Jasmine.

The following statement is required in each BAT test:

`import * from bat::BDD`

This statement imports the Domain Specific Language (DSL) testing library BDD.dwl, which defines
words you frequently use when writing, such as describe, it, GET, POST, and sleep).

This statement imports common matchers, such as mustEqual, mustMatch, every, oneOf, and assert.

The following example shows how you typically begin writing a test:

```text
import * from bat::BDD
import * from bat::Assertions
import * from bat::Mutable


var context = HashMap()
---
describe("the login flow") in [
  it("tries a secured endpoint") in [
    GET `http://127.0.0.1:4567/secured_by_token` with {

    } assert [
      $.response.status mustEqual 401,
    ]
  ],
  it("gets the access token") in [
    POST `http://127.0.0.1:4567/get_access_token` with {} assert [
      $.response.body.new_token mustMatch /accessToken_\d+/,
    ] execute [
      context.set('token', $.response.body.new_token)
    ] assert [
      context.get('token') mustMatch /accessToken_\d+/,
      context.get('token') mustEqual $.response.body.new_token,
      $.response.status mustEqual 200,
    ]
  ],
  it("tries to get a secured endpoint") in [
    GET `http://127.0.0.1:4567/secured_by_token/header` with {
      headers: {
        Authorization: context.get('token')
      }
    } assert [
      $.request.headers.Authorization mustEqual context.get('token'),
      $.response.status mustEqual 200
    ]
  ]
]
```

## About Test Files

Create a `.dwl` file for each functional scenario. A folder-based organization of files is
recommended. This organization accommodates reports the BAT testing generates. For example:

tests ├── CoreServices │ └── Sanity.dwl └── DesignCenter ├── APIDesigner │ └── Designer.dwl └──
MyFolder ├── DataSense.dwl └── GetProjects.dwl

A test file must contain a `describe` expression.

import \* from bat::BDD
---

describe \`Demo scenario\` in \[

\]

A test suite must contain at least one test (.dwl) file.

## Keeping Confidential Information Secure in Tests

In your tests, you can access shared secrets from Anypoint Secrets Manager. Secrets Manager enables
you to securely store sensitive information, such as a password, authentication token, endpoint URL,
or webhook URL.

### Limitations

- Functional Monitoring works only with symmetric key shared secret types from Anypoint Secrets
  Monitor.

- You can use aliases for shared secrets in a test suite only if you plan to run that test suite
  from a private location.

### Configure a Secret in Anypoint Secret Manager

To keep sensitive information secret in tests you run from a private location, create a shared
secret in Secrets Manager.

To configure a shared secret:

1.  Open a secrets group or create a new one. Create the group in the same environment that you are
    using in BAT CLI.

    To find out which environment you are using in BAT CLI:

    1.  Run the command `bat whoami`.

        The output has the ID for the environment.

    2.  Run the command `bat environment ls` to list the environments to which you have access.

    3.  Match the ID from the `bat whoami` command with one of the environments listed.

    4.  If you need to switch to the environment that your secrets group is in, run the command
        `bat environment switch name`, where `name` is the name of the environment.

2.  Select **Shared Secret**.

3.  In the **Type** field, select **Symmetric Key**.

4.  In the **Key** field, paste the sensitive information encoded as a Base64 string.

5.  Paste the Base64 string into the **Confirm Key** field.

After you modify the monitor’s `main.dwl` file to add the secret information to the code, grant the
monitor access to the secrets you configured in Secrets Manager. See
[Grant Your Monitor Access to the Secret](#grant-access-to-secret).

### Grant Your Monitor Access to the Secret

After you modify your monitor to add the secret information, grant the monitor access to the secret.
At runtime, BAT CLI looks up the shared secrets using the aliases.

To grant a monitor access to the secret:

1.  Copy the name of the new shared secret obtained in
    [Configure a Secret in Anypoint Secret Manager](#configure-secret).

2.  At a command prompt, run the `bat grant` command, specifying an alias for the shared secret.
    When you run this command, BAT CLI creates a section named `secrets` in your test suite’s
    `bat.yaml` file, if the section does not already exist. In that section, BAT CLI adds these
    indented lines:

    alias: secretId: "secret-ID"

    - `alias`: The alias that you specified in the `bat grant` command.

    - `secret-ID`: The ID of the secret within Anypoint Secrets Manager. This ID does not appear in
      ASM, so there is no way for someone looking in your `bat.yaml` file to associate the ID with
      any particular secret. The BAT CLI uses this ID to look up the secret that you associated with
      the alias.

### Example of Using an Alias

Use the alias in a test by storing it in a variable, as in this example:

import \* from bat::BDD import \* from bat::Assertions

var mySecret: String = secret('myAlias') default 'notFound'

---

suite(parts="Simple Suite") in \[ it must 'answer 200' in \[ GET '$(config.url)?token=$(mySecret)'
with {} assert \[ $.response.status mustEqual 200 \] execute \] \]

`mySecret`

The variable in which the secret is stored in this example. The variable is declared as a String.

`secret('myAlias')`

The `secret()` function requires the input `'name-of-alias'`, where `name-of-alias` is the alias of
the shared secret that you want to use.

`default 'notFound'`

The message to show if a shared secret with the specified alias does not exist in Anypoint Secrets
Manager.

`$(mySecret)`

The use of the variable `mySecret` to supply the authentication token for the endpoint at the URL
that is defined in the configuration file that was specified when the `bat` command to run the test
suite was entered.

For example, suppose that the configuration file was this:

The example configuration file dev-environment.dwl

{ url: "https://dev.yourcompany.com/shoppingCart" }

In this case, the command to run this test suite, when the command is run in the directory in which
the `bat.yaml` file for the test suite is located and the default profile is used, is this:

bat --config=dev-environment.dwl

At runtime, the BAT CLI replaces the variable with the shared secret that it finds associated with
the specified alias in Anypoint Secrets Manager.

## Test Blocks

Test blocks make the test more readable. You can write every test block as a function call or a
custom interpolation.

### Test Keywords

You use the following keywords and follow Fowler’s _GivenWhenThen_ structure, in tests:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Function Name</th><th>Description</th><th>Stops execution if it fails</th></tr></thead><tbody><tr><td><div><div><p><code>describe</code></p></div></div></td><td><div><div><p>For grouping, which you can nest as deep to add contextual information for reports</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>scenario</code></p></div></div></td><td><div><div><p>Same as describe</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>suite</code></p></div></div></td><td><div><div><p>Same as describe</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>given</code></p></div></div></td><td><div><div><p>Test step, used for preparation</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p><code>when</code></p></div></div></td><td><div><div><p>Test step, normally used to create side effects</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p><code>it</code></p></div></div></td><td><div><div><p>Test step, validations</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>should</code></p></div></div></td><td><div><div><p>Test step</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>must</code></p></div></div></td><td><div><div><p>Test step</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p><code>it should "str"</code></p></div></div></td><td><div><div><p>Test step</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>it must ""</code></p></div></div></td><td><div><div><p>Test step</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p><code>while</code></p></div></div></td><td><div><div><p>Test step</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p><code>until</code></p></div></div></td><td><div><div><p>Test step</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

### About a Test Block

Test blocks have a shorthand name to skip the block described as `x<name>`. For example, the skipped
version of `describe` is `xdescribe`.

```text
describe("A flow")  in [ ... ] // Describes a sequence of test blocks
xdescribe("A flow") in [ ... ] // The same, but skipped.

describe `A flow` in [ ... ]   // The same as describe, but with a custom interpolation
xdescribe `A flow` in [ ... ]  // The same, but skipped.
```

### About Custom Interpolators

Custom interpolators provide a way to call functions and decompose interpolations in two lists:

- The first list contains all the string literals.

- The second one contains the interpolated values.

You do not need to convert the values to strings. Enclose a custom interpolation text and value in
backticks (`` ` ``).

Every item in the following block can be used as custom interpolators and has the `x<name>` version.

```text
import * from bat::BDD         // <-----
import * from bat::Assertions
---
describe `User trades stocks` in [
  scenario `User requests a sell before close of trading` in [
    given `I have 100 shares of MSFT stock` in [
      POST `http://broker/create_stocks` with {
        body: {
          quantity: 100,
          paper: 'MSFT'
        }
      } assert [
        $.response.status == 201
      ]
    ],
    given `I have 150 shares of APPL stock` in [
      POST `http://broker/create_stocks` with {
        body: {
          quantity: 150,
          paper: 'APPL'
        }
      } assert [
        $.response.status == 201
      ]
    ],
    when `I ask to sell 20 shares of MSFT stock` in [
      POST `http://broker/sell_stocks` with {
        body: {
          quantity: 20,
          paper: 'MSFT'
        }
      } assert [
        $.response.status == 201
      ]
    ],
    it should "have 80 shares of MSFT stock" in [
      GET `http://broker/get_stocks/MSFT` with {
        headers: {}
      } assert [
        $.response.status == 200,
        $.response.body.quantity == 80
      ]
    ],
    it should "have 150 shares of APPL stock" in [
      GET `http://broker/get_stocks/APPL` with {
        headers: {}
      } assert [
        $.response.status == 200,
        $.response.body.quantity == 150
      ]
    ]
  ]
]
```

You can also write the block without custom interpolators to conform to your coding style guide.
This doesn’t affect behavior:

```text
import * from bat::BDD         // <-----
import * from bat::Assertions
---
describe("User trades stocks") in [
  scenario("User requests a sell before close of trading") in [
    given("I have 100 shares of MSFT stock") in [
      POST `http://broker/create_stocks` with {
        body: {
          quantity: 100,
          paper: 'MSFT'
        }
      } assert [
        $.response.status == 201
      ]
    ],
    given("I have 150 shares of APPL stock") in [
      POST `http://broker/create_stocks` with {
        body: {
          quantity: 150,
          paper: 'APPL'
        }
      } assert [
        $.response.status == 201
      ]
    ],
    when("I ask to sell 20 shares of MSFT stock") in [
      POST `http://broker/sell_stocks` with {
        body: {
          quantity: 20,
          paper: 'MSFT'
        }
      } assert [
        $.response.status == 201
      ]
    ],
    should("have 80 shares of MSFT stock") in [
      GET `http://broker/get_stocks/MSFT` with {
        headers: {}
      } assert [
        $.response.status == 200,
        $.response.body.quantity == 80
      ]
    ],
    should("have 150 shares of APPL stock") in [
      GET `http://broker/get_stocks/APPL` with {
        headers: {}
      } assert [
        $.response.status == 200,
        $.response.body.quantity == 150
      ]
    ]
  ]
]
```

## Controlling Execution and Deleting Assets

If you get a failure in the middle of a test, you need to delete any created assets. For example,
the user creates an asset, performs a validation, and then deletes it. Typically, that validation
fails, and since it breaks the test, the asset is not deleted and your database starts accumulating
test data. Typically this means changing a `must` to a `should` so that execution can continue, but
not leave a failed asset.

Incorrect Example:

If the update name in line 6 fails, the project is not deleted because the execution stops.

```text
describe `update project names` in [
  it must 'create a project' in [
    createProject()     // OK
  ],
  it must 'update the name' in [
    updateProjectName() // FAILS
  ],
  // Because the previous step is a `must` that failed, execution stops here and the next steps don't execute
  it must 'clean up deleting the project' in [
    deleteProject()     // CANCELLED
  ]
]
```

Use these reserved words to wrap steps to stop or allow execution to continue:

- `should` means something might fail, but it is not mandatory for the test.

- `must` means that something, such as project creation, must execute to continue.

Correct Example:

```text
describe `update project names` in [
  it must 'create a project' in [
    /**
     * Project creation is a MUST, because in this scenario
     * we depend on the created project to continue.
     */
    createProject()     // OK
  ],
  it should 'update the name' in [
    /**
     * Validations are should because the execution must continue
     * if the validation fails.
     */
    updateProjectName() // FAILS
  ],
  // Because the previous step is a should and it failed, continue executing.
  it must 'clean up deleting the project' in [
    deleteProject()     // OK
  ]
]
```

## Executing Steps Selectively

The `assuming` function skips the test if the result is false. This command has the following
syntax:

`[TestBlockExpression] assuming [BooleanExpression] in …​`

For example:

```text
describe `E2E Scenario` in [
  it should 'always do something' in [
    doSomething()
  ],
  it should 'do something else' in [
    doSomethingElse()
  ],
  it should 'sometimes, do something else' assuming (random() > 0.5) in [
    // This is executed randomly, based on          ^^^^^^^^^^^^^^^^ that condition
    doSomethingElse()
  ],
  it should 'do something in dev environments' assuming (config.env == 'DEV') in [
    // This is executed only when                       ^^^^^^^^^^^^^^^^^^^^^ that == true
    doSomethingElse()
  ]
]
```

To make the code more readable and understandable, you can use two aliases for this function. `when`
and `whenNot`. For example:

```text
describe `E2E Scenario` in [
  it should 'always do something' in [
    doSomething()
  ],
  it must 'do something else' when config.runSanity in [
    doSomethingElse()
  ],
  it should 'do something else' when a == b in [
    doSomethingElse()
  ],
  it should 'do something in dev environments' whenNot config.isSmokeTests in [
    doSomethingElse()
  ]
]
```

## Executing Loop Sentences

The while or until functions run the test while (or until) a condition becomes true or false.

Signature of the while function:

- `while( sentence , condition, time per request, number of retries)`

- `do { sentence } while (condition) //→ Default values: 1 second and 3 retries`.

Signature for the until function:

- `until( sentence , condition, time per request, number of retries)`

- `do { sentence } until (condition) //→ Default values: 1 second and 3 retries`.

Example:

```java
dwl
import * from bat::BDD
import * from bat::Assertions
import * from bat::Types
---
suite("Example for until and while") in [
  it should 'test the while prefix' in [
    while(() -> GET `http://apimon.cloudhub.io/users` with {},
    (x: BATHttpStep) -> x.result.response.status != 200, 10000, 5)
  ],
  it should 'test the while infix' in [
    do {
      () -> GET `http://apimon.cloudhub.io/users` with {} assert [
          $.response.status mustEqual 200
        ]
    } while ($.response.status != 200)
  ],
  it should 'test the until prefix' in [
    until(() -> GET `http://apimon.cloudhub.io/users` with {},
     (x: BATHttpStep) -> x.result.response.status != 200, 10000, 5)
  ],
  it should 'test the until infix' in [
    do {
      () -> GET `http://apimon.cloudhub.io/users` with {} assert [
          $.response.status mustEqual 200
        ]
    } until ($.result.response.status != 200)
  ]
]
```

## See Also

- [MuleSoft Trailblazer Community](https://trailhead.salesforce.com/trailblazer-community/neighborhoods/mulesoft)

- [Salesforce Help](https://help.salesforce.com)

- [Using Secrets to Mask Sensitive Information in Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-mask-info-in-monitors)

<!-- document id=47887e89801c9b83b47c52cec0f4cd94521c8116a59adbd0317fad9e6cc49d36 url=/mulesoft/current/en-us/api-functional-monitoring/bat-reporting-task.md -->

---
product: API Functional Monitoring
---

# Configuring and Viewing Reports

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can configure BAT for use with these reporting systems.

- New Relic

- PagerDuty

- Slack

- Sumo Logic

- Email

You can also configure custom reports and reports that are sent to a location on your computer.

## New Relic

Using New Relic with API Functional Monitoring, you can view metrics from test suites in New Relic.
Metrics include the times of each test, performance losses detected, and alert schedules.

### Configure Reporting in New Relic

1.  Obtain your New Relic license key. For details on how to do this, see the
    [New Relic documentation](https://docs.newrelic.com/).

2.  In your `bat.yaml` file, create the `reporters` section, if one doesn’t already exist in the
    file. On a blank line, type `reporters:`.

3.  In your `bat.yaml` file, add New Relic as a reporter by adding these indented lines to the
    `reporters` section:

    ```yaml
    - type: NewRelic
      options:
        NEW_RELIC_LICENSE_KEY: <new-relic-license-key>
        DISABLED_FOR_CONFIGS: dev,qa
    ```

    - `new-relic-license-key`: Specify the New Relic license key enclosed in double quotation marks.

      You can configure a secret to securely pass the license key. If you do so, use the secret’s
      alias in `new-relic-license-key`. The alias must be between backticks. See
      [Configure a Secret in Anypoint Secret Manager](#configure-secret).

    - `DISABLED_FOR_CONFIGS`: Disables the reporter for one or more configurations. The value is the
      name of one configuration or multiple names that are separated by commas. Names do not include
      the `.dwl` file extension.

### What to Do Next

After a test runs, go to New Relic and click **Metrics**. The BAT test metrics appear.

Click the test suite name to see the result of the test.

### Find AFM metrics in New Relic

To locate AFM metrics in New Relic:

1.  In New Relic, click **All capabilities** in the left navigation.

2.  Click **Data explorer**.

3.  Click **Metrics**.

4.  In the search bar, type `successfully-afm-execution`.

5.  (Optional) To narrow the results, add a filter by agent and type `Api Functional Monitoring`.

6.  Click the metric name to view the time series and related dimensions.

If you prefer NRQL, you can query metrics directly, for example:

```sql
FROM Metric
SELECT count(*)
WHERE metricName = 'successfully-afm-execution'
SINCE 1 hour ago TIMESERIES
```

Use additional filters (for example, by test suite name) to focus on a specific monitor run or
environment.

## PagerDuty

The integration of BAT with PagerDuty generates an incident when a test fails and triggers
configured PagerDuty alerts. If a monitor always fails with the same error, BAT does not generate a
new issue, but instead ignores these errors.

### Configure Reporting in PagerDuty

1.  In PagerDuty, configure an integration:

    1.  Select **Configure** > **Services**.

    2.  Select the integration.

2.  Copy the routing key.

3.  In your `bat.yaml` file, create the `reporters` section, if one doesn’t already exist in the
    file. On a blank line, type `reporters:`.

4.  In your `bat.yaml` file, add PagerDuty as a reporter by adding these indented lines to the
    `reporters` section:

    ```yaml
    - type: PagerDuty
      outFile: filename.json
      options:
        PAGER_DUTY_ROUTING_KEY: "service_key"
        DISABLED_FOR_CONFIGS: dev,qa
    ```

    - `filename.json`: Specify a name for the output file to create.

    - `service_key`: Specify the routing key.

      You can configure a secret to securely pass the service key. If you do so, use the alias that
      you used for the secret for the service key when you ran the `bat grant` command. The alias
      must be between carets. See
      [Configure a Secret in Anypoint Secret Manager](#configure-secret).

    - `DISABLED_FOR_CONFIGS`: Disables the reporter for one or more configurations. The value is the
      name of one configuration or multiple names that are separated by commas. Names do not include
      the .dwl file extension.

### What to Do Next

If a test fails, look in PagerDuty for the report.

## Slack

You can integrate BAT and Slack to send notifications to a Slack channel when tests fail. A
notification provides the name of the suite in which the error occurs.

### Configure Failure Notifications in Slack

1.  Create a webhook:

    1.  In Slack, go to your organization’s app directory page.

    2.  Search for "Incoming WebHooks" and add a configuration.

2.  Choose or create a channel to post notifications to.

3.  Copy the webhook URL of your new configuration.

4.  In your `bat.yaml` file, create the `metadata` and `reporters` sections, if they do not already
    exist in the file. On a blank line, enter `metadata:`. A few blank lines after that, enter
    `reporters:`.

5.  In your `bat.yaml` file, add the Slack channel to the `metadata` section by adding this indented
    line:

    ```yaml
    slack_channel: slack_channel
    ```

    - `slack_channel`: Specify the name of the Slack channel that you want to send notifications to.

6.  In your `bat.yaml` file, add Slack as a reporter by adding these indented lines to the
    `reporters` section:

    ```yaml
    - type: Slack
      outFile: filename.json
      options:
        SLACK_WEBHOOK: "webhook_URL"
        SEND_NOTIFICATION_IF_PASSED: true
        AT_HERE_ENABLED: true
        DISABLED_FOR_CONFIGS: dev,qa.
    ```

    - `filename.json`: Specify a name for the output file to create.

    - `webhook_URL`: Specify the URL of the webhook.

      You can configure a secret to securely pass the webhook URL. If you do so, use the alias that
      you used for the secret for the webhook URL when you ran the `bat grant` command. The alias
      must be between carets. See
      [Configure a Secret in Anypoint Secret Manager](#configure-secret).

    - `SEND_NOTIFICATION_IF_PASSED`: Setting this option to `true` causes a notification to be sent
      if a test passes.

    - `AT_HERE_ENABLED`: Setting this option to `true` adds `@here` to a notification if a test
      fails.

    - `DISABLED_FOR_CONFIGS`: Disables the reporter for one or more configurations. The value is the
      name of one configuration or multiple names that are separated by commas. Names do not include
      the `.dwl` file extension.

## Sumo Logic

To use Sumo Logic, you create a collection and specify it in the bat.yaml. The collection can be
shared with other tests or used only as a monitor. At the end of each execution, BAT generates a
post to SUMO that sends the trade-off information of requests and responses that were executed
during the test. This enables you to see expected results and how the test behaves.

You must provide the URL of the endpoint of the collection.

You can use BAT to post a log in the specified collection, and create dashboards.

### Configure Reporting in Sumo Logic

1.  In Sumo Logic, select Set Up Streaming Data in the setup wizard.

2.  Select **Your Custom App** > **HTTP Source** or **All Other Sources** > **HTTP Source** and
    specify the source category.

3.  Copy the endpoint URL.

4.  In your `bat.yaml` file, create the `reporters` section, if one doesn’t already exist in the
    file. On a blank line, type `reporters:`.

    ```yaml
    - type: SumoLogic
      outfile: filename.json
      options:
        SUMO_ENDPOINT: endpoint-URL
        DISABLED_FOR_CONFIGS: dev,qa.
    ```

    - `filename.json`: Specify a name for the output file to create.

    - `endpoint-URL`: The URL of the endpoint for the collection.

      You can configure a secret to securely pass the endpoint URL key. If you do so, use the alias
      that you used for the secret for the endpoint URL key when you ran the `bat grant` command.
      The alias must be between carets. See
      [Configure a Secret in Anypoint Secret Manager](#configure-secret).

    - `DISABLED_FOR_CONFIGS`: Disables the reporter for one or more configurations. The value is the
      name of one configuration or multiple names that are separated by commas. Names do not include
      the .dwl file extension.

## Email

To email test reports that indicate failures, specify any email addresses that you want to send
reports to. Each report includes the name of the suite in which the error occurs and a list of the
statements.

Because reports are emailed only for tests created in or uploaded to the API Functional Monitoring
in Anypoint Platform, after you add the reporters to your test in BAT CLI, upload the test. You can
alternatively add the email reporting tool in the monitor’s **Notifications** tab after you upload
the test.

1.  In your `bat.yaml` file, create the `reporters` section, if one doesn’t already exist in the
    file. On a blank line, type `reporters:`.

    ```yaml
    EMAILS: <alias_1>;<alias_2>;<alias_3>
    ```

2.  If you do not want to keep an email address secret, add these lines to the `reporters` section
    in your `bat.yaml` file:

    ```yaml
    - type: Email
      options:
        EMAILS: email_address
        DISABLED_FOR_CONFIGS: dev,qa
    ```

    - `email_address`: Specify the email address to send notifications to. If you want to use more
      than one email address, separate them with semicolons:

      ```yaml
      EMAILS: email_address1;email_address2;email_address3
      ```

      You can configure a secret to securely pass the email addresses. If you do so, use the alias
      that you used for the secret for each email address when you ran the `bat grant` command. The
      alias must be between carets. To specify multiple email address aliases, put each alias
      between carets and separate the aliases with semicolons. See
      [Configure a Secret in Anypoint Secret Manager](#configure-secret).

    - `DISABLED_FOR_CONFIGS`: Disables the reporter for one or more configurations. The value is the
      name of one configuration or multiple names that are separated by commas. Names do not include
      the .dwl file extension.

## Custom Reports

BAT publishes the result.json with a post to the URL that you specify in the bat.yaml file. You can
add headers if necessary.

To publish custom reports for a test suite, add the following indented lines to the `reporters`
section of the `bat.yaml` file, replacing the value for `URL` with your own URL.

```yaml
reporters:
  - type: Custom
    options:
      URL: "http://www.httpbin.org/post"
      HEADERS: "'Authorization':'Bearer token','Content-Type':'application/json'"
      DISABLED_FOR_CONFIGS: dev,qa
```

- `DISABLED_FOR_CONFIGS`: Disables the reporter for one or more configurations. The value is the
  name of one configuration or multiple names that are separated by commas. Names do not include the
  .dwl file extension.

## Local Reports

BAT generates basic types of reports locally in JSON and HTML. When you execute tests, the path to
the reports appears in the output.

Example:

```yaml
Reporter: /var/folders/vz/56jp75d941592x_1d8mfy9f40000gn/T/bat_report_20180320121736.json
Reporter: /var/folders/vz/56jp75d941592x_1d8mfy9f40000gn/T/bat_report_20180320121736.html
```

### To Configure Local Report Generation

In the bat.yaml file, specify a `type` field to generate local reports. For example:

```yaml
reporters:
  - type: JSON
    outFile: JSON.json
  - type: HTML
    outFile: HTML.html
  - type: JUnit
    outFile: JUnit.xml
```

### To Create a Local Custom Report

You can generate a custom report based on a DataWeave transformation that is specified in the
bat.yaml using the `file` keyword.

```yaml
reporters:
  - type: Local
    file: reporter/transform.dwl
    outFile: local.json
```

The transform.dwl file contains the following code:

```dataweave
%dw 2.0
output application/json
var result = if (payload.result.pass[0]) " is ok" else " failed"
---
{
    result: "The suite <" ++ payload.name ++ "> with assertion <" ++ payload.result[0].name ++ ">" ++ result
}
```

And the result is:

```dataweave
{
  "result": "The suite <Hello world suite> with assertion <answer 200> is ok"
}
```

## Configure a Secret in Anypoint Secret Manager

To keep sensitive information secret in tests you run from a private location, create a shared
secret in Secrets Manager.

To configure a shared secret:

1.  Open a secrets group or create a new one. Create the group in the same environment that you are
    using in BAT CLI.

    To find out which environment you are using in BAT CLI:

    1.  Run the command `bat whoami`.

        The output has the ID for the environment.

    2.  Run the command `bat environment ls` to list the environments to which you have access.

    3.  Match the ID from the `bat whoami` command with one of the environments listed.

    4.  If you need to switch to the environment that your secrets group is in, run the command
        `bat environment switch name`, where `name` is the name of the environment.

2.  Select **Shared Secret**.

3.  In the **Type** field, select **Symmetric Key**.

4.  In the **Key** field, paste the sensitive information encoded as a Base64 string.

5.  Paste the Base64 string into the **Confirm Key** field.

### Grant Your Monitor Access to the Secret

After you modify your monitor to add the secret information, grant the monitor access to the secret.
At runtime, BAT CLI looks up the shared secrets using the aliases.

To grant a monitor access to the secret:

1.  Copy the name of the new shared secret obtained in
    [Configure a Secret in Anypoint Secret Manager](#configure-secret).

2.  At a command prompt, run the `bat grant` command, specifying an alias for the shared secret.
    When you run this command, BAT CLI creates a section named `secrets` in your test suite’s
    `bat.yaml` file, if the section does not already exist. In that section, BAT CLI adds these
    indented lines:

    alias: secretId: "secret-ID"

    - `alias`: The alias that you specified in the `bat grant` command.

    - `secret-ID`: The ID of the secret within Anypoint Secrets Manager. This ID does not appear in
      ASM, so there is no way for someone looking in your `bat.yaml` file to associate the ID with
      any particular secret. The BAT CLI uses this ID to look up the secret that you associated with
      the alias.

## See Also

[Creating Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor)
[Using Secrets to Mask Sensitive Information in Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-mask-info-in-monitors)

<!-- document id=9dba805fcf8b7cf90e92cd145f5cd094d483c2f11563bb3cf6eeba60faf06ed9 url=/mulesoft/current/en-us/api-functional-monitoring/afm-create-monitor.md -->

---
product: API Functional Monitoring
---

# Creating Monitors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You create monitors via the Functional Monitoring UI or by uploading test suites written in BAT, a
Behavior Driven Development (BDD) language. Both methods enable you to create tests against one or
more endpoints, and to create test schedules that run at specified intervals.

This procedure describes creating monitors via the Functional Monitoring UI.

## Before You Begin

Ensure that you have the following permissions set in Access Management:

- **Anypoint Monitoring > Viewer** or **Anypoint Monitoring > Administrator**

  and

- **Exchange > Exchange Administrator** or **Exchange > Exchange Contributor**

An Anypoint Platform administrator for your organization grants permission. See
[Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions).

## Create a Monitor

To create a monitor:

1.  Click **Create Monitor** in the **Functional Monitoring** section of Anypoint Monitoring.

2.  Under **Step 1 - Setup the monitor**:

    1.  Specify a monitor name.

    2.  Select a testing location.

    3.  Set the monitoring schedule.

3.  Click the **Step 2 - Select endpoints** tab and set up the tests as follows for each endpoint:

    1.  By default, the monitor validates self-signed certifications for each endpoint, so
        **Validate SSL Certificate** is toggled on. To allow unsafe self-signed certifications for
        an endpoint, toggle **Validate SSL Certificate** off.

    2.  Select the method and enter the endpoint URL.

    3.  Search for, select, or configure custom headers and insert a value for each header.

    4.  For POST, PUT, or PATCH endpoints, optionally insert body content.

    5.  Optionally select headers and insert their values.

    6.  Select assertion information.

    7.  Preview the test by clicking **Run now** under **Preview the result of your monitor**.

4.  Click the **Step 3 - Set notifications** tab.

    - Optionally select notifiers from the list of integrated reporting tools and enter the required
      information in the value field for each selected notifier:

      <table><colgroup><col> <col></colgroup><thead><tr><th>Reporting Tool</th><th>Required Information</th></tr></thead><tbody><tr><td><p>New Relic</p></td><td><p>License Key</p></td></tr><tr><td><p>PagerDuty</p></td><td><p>RoutingKey</p></td></tr><tr><td><p>Slack</p></td><td><p>Webhook</p></td></tr><tr><td><p>SumoLogic</p></td><td><p>Endpoint</p></td></tr><tr><td><p>Email</p></td><td><p>Email address</p></td></tr></tbody></table>

      To hide the required information in the monitor files, see
      [Configuring and Viewing Reports](https://docs.mulesoft.com/api-functional-monitoring/bat-reporting-task).

5.  Click **Create Monitor**.

> [!NOTE] On the **Step 2 - Select endpoints** tab, you can alternatively click **Switch to code
> editor** to edit the monitor as BAT source. For more details, see
> [BDD Test-Writing Syntax Reference](https://docs.mulesoft.com/api-functional-monitoring/bat-bdd-reference).

## See Also

- [API Functional Monitoring with the Blackbox Automated Testing (BAT) CLI](https://docs.mulesoft.com/api-functional-monitoring/bat-top)

- [Managing Permissions](https://docs.mulesoft.com/access-management/managing-permissions)

- [Modifying Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-modify-monitor)

- [Adding Schedules](https://docs.mulesoft.com/api-functional-monitoring/afm-add-schedule)

- [Monitoring the Endpoints of Public APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-public-apis)

- [Monitoring the Endpoints of Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-private-apis)

<!-- document id=da857a33bcb33dc0795ed38b0dd200aae5d313bcbd028f81c6c589841183e832 url=/mulesoft/current/en-us/api-functional-monitoring/bat-schedule-for-particular-location.md -->

---
product: API Functional Monitoring
---

# Creating Monitors That Use a Specific Location

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To create a monitor that uses a specific location:

1.  Run the following command to list the locations that are in your default profile:

    ```none
    bat location ls
    ```

    > [!NOTE] To use a non-default profile, add `--profile=<name-of-profile>` to the commands in
    > these steps.

2.  Find the entry for the location that you want to use.

    For public locations, the value of the `organizationId` field is `public`. For private
    locations, the value is your organization ID.

    Here is example output from this command:

    ```none
    organizationId: 612dbc11-a043-4b8b-b76e-7d51f84723c7
    targets:
    -
      id: 75c403a6-8054-43ec-b611-63b9efff820d
      name: us-east-1
      transport: LAMBDA
      organizationId: public
    -
      id: 799baaeb-3c86-4798-b5b4-6d6954254229
      name: us-east-2
      transport: LAMBDA
      organizationId: public
    -
      id: b4b4db50-bcbb-4b9a-93e1-50259fd100f7
      name: myLocation
      transport: MULE
      organizationId: 612dbc11-a043-4b8b-b76e-7d51f84723c7
    ```

3.  Copy to your clipboard the value of the `id` field for the location that you want to use.

    For example, to use the private location in the example output, copy the value of the `id` field
    for the third location listed.

4.  Create the schedule, using the `--target` parameter and pasting in the value of the `id` field,
    as in this example:

    ```none
    bat schedule create --target=b4b4db50-bcbb-4b9a-93e1-50259fd100f7
    ```

    > [!NOTE] This schedule uses the default interval of 15 minutes.

    The output of the `bat schedule create` command looks like this:

    ```none
    #Creating artifact...
      + exchange.json
      + .DS_Store
      + config/default.dwl
      + config/qax.dwl
      + config/devx.dwl
      + config/stgx.dwl
      + tests/HelloWorld.dwl
      + bat.yaml
    # Creating artifact...OK
    # Uploading 612dbc11-a043-4b8b-b76e-7d51f84723c7:HelloWorldSuite:0.0.1
    # Version 0.0.1 published
    scheduleId: 345305b4-0244-4a75-a304-220495e2e34a
    ```

5.  If you run the `bat schedule ls` command, you see an entry like this one:

```none
# HelloWorldSuite
# every 15 minutes
id: 345305b4-0244-4a75-a304-220495e2e34a
test: 612dbc11-a043-4b8b-b76e-7d51f84723c7:HelloWorldSuite
version: 0.0.1
organizationId: 612dbc11-a043-4b8b-b76e-7d51f84723c7
config: default
target:
  id: b4b4db50-bcbb-4b9a-93e1-50259fd100f7
  name: myLocation
  transport: MULE
nextExecution: 2019-09-27T02:15:00Z
cron: 0 */15 * * * ? *
active: true
```

<!-- document id=2cc3e2707638e72e46c655adf7d2a1cd147a1f1d849483bf06ac1921912925a9 url=/mulesoft/current/en-us/api-functional-monitoring/afm-create-private-location.md -->

---
product: API Functional Monitoring
---

# Creating Private Locations

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A private location is a Mule application that runs in an environment in CloudHub 1.0 or Cloudhub
2.0. You can run tests against APIs that are accessible only within the private location. The
private location environment might have an Anypoint VPC associated with it. You can create multiple
private locations in a single instance of Anypoint VPC.

You can create a private location when you:

- [Create a monitor](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor)

- [Add a schedule](https://docs.mulesoft.com/api-functional-monitoring/afm-add-schedule) to a monitor

- [Modify a schedule](https://docs.mulesoft.com/api-functional-monitoring/afm-modify-schedule) in a monitor

This procedure explains how to create a private location when you modify a schedule.

For information about private locations and their uses, see
[Monitoring the Endpoints of Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-private-apis).

## Before You Begin

- Ensure that your Anypoint Platform organization has a subscription to Anypoint Virtual Private
  Cloud.

- Ensure that you have the following permission set in Access Management:

  - **Runtime Manager > Create Applications**

An Anypoint Platform administrator for your organization grants permission. See
[Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions).

## Create a Private Location

To create a private location:

1.  When creating a test or schedule, click the field under **Select location** and select **Create
    new location**.

2.  Name the location.

    The name can be up to 255 characters, and can include spaces and special characters.

3.  Select the environment for the tests.

4.  Select the deployment target.

5.  Complete the creation of the test or schedule. By default, it uses a 0.2 vCores replica size.

> [!NOTE] If your deployment target is set to any variant of CloudHub 2.0, a connected app is
> created automatically.

\+ While API Functional Monitoring is registering the private location, the status indicator is
yellow. After the location is successfully registered, the status indicator is green.

\+ . If the status indicator is red: .. Navigate to Runtime Manager and restart the
application/worker cloudhub application. .. Check the logs for the application/worker cloudhub
application to troubleshoot the issue.

## What to Do Next

You can now run tests from the private location, either by adding a schedule that uses the location
or by modifying an existing schedule to use it.

## See Also

- [Creating Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor)

- [Adding Schedules](https://docs.mulesoft.com/api-functional-monitoring/afm-add-schedule)

- [Modifying Schedules](https://docs.mulesoft.com/api-functional-monitoring/afm-modify-schedule)

- [Managing Permissions](https://docs.mulesoft.com/access-management/managing-permissions)

- [Virtual Private Cloud](https://docs.mulesoft.com/cloudhub/virtual-private-cloud)

<!-- document id=4722019ae3bce955068641bf451f4b829257d7de332c2768f1d9f8dfdb432d91 url=/mulesoft/current/en-us/api-functional-monitoring/afm-delete-monitor.md -->

---
product: API Functional Monitoring
---

# Deleting Monitors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Although you can easily delete unnecessary monitors, there is no cost in keeping them.

## Before You Begin

Ensure that your user ID has the following permission set in Access Management:

- **Exchange > Exchange Administrator**

See [Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions).

## Delete a Monitor

Delete a monitor either from the homepage or from its detail page.

To delete a monitor from the homepage:

1.  Hover over the test to delete.

2.  Click **Delete** (![afm ui trash button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-trash-button.png)).

3.  In the **Delete Monitor** dialog, click **Delete**.

To delete a monitor from its detail page:

1.  Select the monitor that you want to delete.

2.  Click the monitor.

3.  Click **More** (![afm ui more button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-more-button.png)) > **Delete Monitor**.

4.  In the **Delete Monitor** dialog, click **Delete**.

    The monitor and its schedules are deleted. The workers provisioned for the schedules are also
    deleted, and their consumed resources are made available to other workers.

<!-- document id=1788394c0a8bb2662ff04655f91fe4d88d189b22c3b40e180ddf2100faef0092 url=/mulesoft/current/en-us/api-functional-monitoring/afm-delete-schedule.md -->

---
product: API Functional Monitoring
---

# Deleting Schedules

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You might want to delete a schedule for any of the following reasons:

- You have finished testing endpoints of a public API and you want to free resources for testing
  endpoints of a different public API.

- You have finished testing endpoints of a private API.

- You have more than one schedule running the same test and you no longer need one of the schedules.

> [!NOTE] Be sure that you want to delete the schedule. There is no opportunity to confirm the
> deletion.

## Before You Begin

- Before you can delete a schedule, you must have the following permission set in Access Management:

  - **Exchange > Exchange Administrator**

- Before you can delete a private location, you must have the following permission set in Access
  Management:

  - **Runtime Manager > Delete Applications**

An Anypoint Platform administrator for your organization grants permission. See
[Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions).

## Delete a Schedule

Anypoint Functional Monitoring provides two methods for deleting a schedule.

To delete a schedule from the **Schedules** table of a monitor:

1.  Select the monitor that contains a schedule to delete.

2.  Locate the schedule in the table and click **More**
    (![afm ui more button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-more-button.png)) > **Delete Schedule**.

To delete a schedule from the table of schedules that use a specific location:

1.  Display the list of locations by opening the **Locations Manager** in the homepage.

2.  Select the location from which you want to delete a schedule.

3.  Locate the schedule in the table and click **More**
    (![afm ui more button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-more-button.png)) > **Delete Schedule**.

    - If the deleted schedule was the only schedule running a specific test, the worker for that
      test no longer exists.

    - If the schedule was the only schedule using a private location, you have the option to delete
      that private location.

## See Also

- [Adding Schedules](https://docs.mulesoft.com/api-functional-monitoring/afm-add-schedule)

- [Managing Permissions](https://docs.mulesoft.com/access-management/managing-permissions)

<!-- document id=d30f5493768c5f44d36e3b69d4c35a05abf01ed70fddd61f212f47ffdf47b293 url=/mulesoft/current/en-us/api-functional-monitoring/afm-download-test.md -->

---
product: API Functional Monitoring
---

# Downloading Monitors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can download a monitor and modify it on your computer. Then, you can either run the monitor by
using the BAT CLI or upload the monitor into the online interface for API Functional Monitoring.

If you are new to writing monitors manually, you can download monitors, see how they are structured,
and view the content of the files. The knowledge you gain can help you write your own monitors.

## Download a Monitor

1.  Select the monitor to download.

2.  Click the monitor to enter the monitor detail page.

3.  Click **More** (![afm ui more button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-more-button.png)) > **Download Monitor** to
    download a monitor as BAT source.

    The ZIP file is downloaded with the following naming convention:

    `<your Anypoint Platform group ID>_<the name of the monitor>_<the test version>.zip`

<!-- document id=f0f48e8ed96721f1ddc790c766ac55fe2f31a013ce1ae39edc10c56415453f77 url=/mulesoft/current/en-us/api-functional-monitoring/bat-example-test-suite.md -->

---
product: API Functional Monitoring
---

# Example of a Test Suite

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To see the content of an example test suite, in a terminal create a directory in your computer’s
filesystem. Then, change to that directory and run the `bat init` command. The command creates these
folders and files:

. ├── bat.yaml ├── config │   ├── default.dwl │   ├── devx.dwl │   ├── qax.dwl │   └── stgx.dwl └──
tests └── HelloWorld.dwl

The `bat.yaml` file is the main file for the test suite. This example contains these lines:

suite: name: "Hello World Suite" files:

- file: tests/HelloWorld.dwl reporters:
  - type: HTML outFile: /tmp/HTML.html

# - type: SumoLogic

# options:

# SUMO\_ENDPOINT: <sumo\_source>

# - type: PagerDuty

# options:

# PAGER\_DUTY\_ROUTING\_KEY: <routing\_key>

# - type: Slack

# options:

# SLACK\_WEBHOOK: <webhook\_url>

# - type: Email

# options:

# EMAILS: <email\_list>

# - type: NewRelic

# options:

# NEW\_RELIC\_LICENSE\_KEY: <license\_key>

# - type: JSON

# outFile: /tmp/JSON.json

# - type: JUnit

# outFile: /tmp/JUnit.xml

Every test suite must contain a `bat.yaml` file at its root level.

## The `suite` Section of the example `bat.yaml` File

The `suite` section names the suite. You can use any names that you like for the suites that you
write.

## The `files` Section of the example `bat.yaml` File

This example test suite contains only one test. The test is listed in the `files` section as the
file `HelloWorld.dwl` in the `tests` folder.

As you create tests, you add references to them in your `bat.yaml` file. For example, suppose that
in your test-suite directory you create a folder named `api-tests` and write a test named
`first-test.dwl` in that folder. In the `files` section of your `bat.yaml` file, you add the
following indented line:

file: api-tests/first-test.dwl

If you write a second test, this one named `second-test.dwl`, you add this line next:

file: api-tests/second-test.dwl

The order in which you list the tests determines the order in which the BAT CLI runs them. In this
example, the test `orderFulfillment.dwl` runs before the test `shoppingCart.dwl`:

files: file: retail-site-tests/orderFulfillment.dwl file: retail-site-tests/shoppingCart.dwl

To run the `orderFulfillment.dwl` test after the `shoppingCart.dwl` test, you can change the order
in which they are listed:

files: file: retail-site-tests/shoppingCart.dwl file: retail-site-tests/orderFulfillment.dwl

Finally, you can create more than one folder to contain the tests in a test suite. You can even
create subfolders within the folders that contain your tests. Just be sure that you provide the
correct relative path when you list a test in the `files` section of your `bat.yaml` file.

## The `reporters` Section of the `bat.yaml` File

This section is for configuring various tools or third-party applications to report test failures.
In this example, a failure of the `HelloWorld.dwl` test prompts the BAT CLI to write a report of the
failure to the file `/tmp/HTML.html`. For information about setting up reports, see
[Configure and View Test Reports](https://docs.mulesoft.com/api-functional-monitoring/bat-reporting-task).

## The `secrets` Section of the `bat.yaml` File

If you plan to run a test suite from a private location, you can use the BAT CLI’s integration with
Anypoint Secrets Manager to use shared secrets in your tests.

## The `config` Folder

You can store variables in the files in the `config` folder. For example, suppose that you’re
developing an API and you deploy it to two different environments: `dev` and `qa`. The endpoint URL
for the first is `dev.myapi.com` and for the second `qa.myapi.com`. The API is intended to behave
the same in both environments.

You want to test the API in both environments. However, instead of coding two tests, one for the
deployment of the API in `dev` and one for the deployment of the API in `qa`, you can create a
configuration file for each environment. In each configuration file, you can place a variable named
`url` that holds that endpoint URL for the corresponding environment:

The content of `dev.dwl`, the configuration file for the `dev` environment

{ url: "dev.myapi.com" }

The content of `qa.dwl`, the configuration file for the `qa` environment

{ url: "qa.myapi.com" }

In your test, you can use the `url` variable by placing it within this syntax: `$(config.variable)`,
where _variable_ is the name of the variable that you want to use. Here is an example test that uses
the `url` variable in a `GET` request to test the assertion that the response code must be 200:

import \* from bat::BDD import \* from bat::Assertions
---

suite("Hello world suite") in \[ it must 'answer 200' in \[ GET
\`$(config.url)\` with {} assert \[
      $.response.status mustEqual 200 \] \] \]

When you run the test, you can use the `--config` parameter to specify which configuration file to
use. (If you upload your test suite as a monitor to API Functional Monitoring in Anypoint Platform,
you can specify the configuration to use when you create a schedule for the monitor.)

Use JSON for the format of your configuration files, and `.dwl` as the file extension. You can put
as many variables as you need in each file.

## The `tests` Folder

In the example test suite, the test `HelloWorld.dwl` is in a folder named `tests`. As explained in
the section about the `bat.yaml` file in this example, the `files` section in the `bat.yaml` file
points to the tests in a test suite.

```yaml
files:
  - file: tests/HelloWorld.dwl
```

In your own test suites, the folders that contain your tests can have any name that is valid for
your filesystem. You can also place tests in multiple folders.

<!-- document id=9a49a5ef678cb085c621d2c69d3d13645539d3168c79b02891946e81de30abb6 url=/mulesoft/current/en-us/api-functional-monitoring/afm-getting-started.md -->

---
product: API Functional Monitoring
---

# Getting Started with API Functional Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

After you become familiar with the API Functional Monitoring UI and concepts covered in the
[API Functional Monitoring Overview](https://docs.mulesoft.com/api-functional-monitoring/), you are ready to start monitoring your APIs.

## Before You Begin

To use API Functional Monitoring, you must have the permissions required for the actions you want to
execute. Permissions are set by your organization administrator.

<table><colgroup><col> <col></colgroup><thead><tr><th>Permission</th><th>Actions</th></tr></thead><tbody><tr><td><p>Create Applications (Runtime Manager)</p></td><td><p>Create private locations</p></td></tr><tr><td><p>Delete Applications (Runtime Manager)</p></td><td><p>Delete private locations</p></td></tr><tr><td><p>Manage Settings (Runtime Manager)</p></td><td><p>Update private locations</p></td></tr><tr><td><p>View Environment</p></td><td><p>Log in using BAT CLI</p></td></tr><tr><td><p>View Organization</p></td><td><p>Use Secrets Manager through BAT CLI</p></td></tr><tr><td><p>Exchange Contributor (Exchange)</p></td><td><p>Create or modify a monitor; add or modify a schedule</p></td></tr><tr><td><p>Exchange Administrator (Exchange)</p></td><td><p>Create, modify, or delete a monitor; add, modify, or delete a schedule</p></td></tr></tbody><tfoot><tr><td><p>Grant access to secrets (Secrets Manager)</p></td><td><p>Use Secrets Manager</p></td></tr></tfoot></table>

## Monitor Your APIs Using the Functional Monitoring UI

To monitor your APIs in Functional Monitoring:

1.  [Create monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor) for the APIs that you want to test. This includes:

    - Adding locations and schedules

    - Configuring tests for the API endpoints

    - Setting notifications through reporting tools

2.  [View monitor history](https://docs.mulesoft.com/api-functional-monitoring/afm-view-test-history).

## Monitor Your APIs Using BAT CLI

To monitor your APIs using BAT CLI:

1.  [Install BAT CLI](https://docs.mulesoft.com/api-functional-monitoring/bat-install-task).

2.  Create a test suite [from an example](https://docs.mulesoft.com/api-functional-monitoring/bat-example-test-suite) or by
    [populating the lines yourself](https://docs.mulesoft.com/api-functional-monitoring/bat-start-new-project).

3.  [Write tests](https://docs.mulesoft.com/api-functional-monitoring/bat-write-tests-task) using BDD test-writing syntax.

4.  [Run a test suite](https://docs.mulesoft.com/api-functional-monitoring/bat-execute-task).

5.  [Schedule testing and monitoring](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-test-task).

6.  [Create monitors that use a specific location](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-for-particular-location).

## Additional Options and Reporting

Additionally you can:

- [Download monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-download-test) from Functional Monitoring to use them with BAT CLI or to
  modify them to create more complex test cases.

- [Upload monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-upload-monitor) you have manually written or modified to use them in
  Functional Monitoring.

- [Use BAT CLI to configure monitoring reports](https://docs.mulesoft.com/api-functional-monitoring/bat-reporting-task) in one of the supported
  reporting systems.

- [Write and run BAT tests in IntelliJ IDEA](https://docs.mulesoft.com/api-functional-monitoring/bat-intellij-idea).

## See Also

- [API Functional Monitoring Overview](https://docs.mulesoft.com/api-functional-monitoring/)

- [Managing Permissions in Access Management](https://docs.mulesoft.com/access-management/managing-permissions)

<!-- document id=e7ed5fe3f309893d786a4562becface3692e16b036cd5d2f0a24dba9c0db05f5 url=/mulesoft/current/en-us/api-functional-monitoring/bat-write-tests-task.md -->

---
product: API Functional Monitoring
---

# Getting Started Writing Tests

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A test suite is composed of the following elements:

- A directory that contains a main file named `bat.yaml` that describes the structure of your test
  suite

- A `config` folder that contains files in which you specify variables

- One or more folders in which you write tests

Tests are written in the BDD Test-Writing syntax and use the `.dwl` file extension.

## Before You Begin

Before you can write and run tests, you must have access to an Anypoint Platform account.

## Use Examples to Learn the Basics

Learn the basics of writing tests using the provided examples.

To select examples:

1.  In the **Create Monitor** page, click **Switch to code editor**.

2.  In the selector menu for the code editor, select a test example. Examples include:

    - Test an expected status code

    - Validate multiple assertions

    - Set and reuse variables

    - Iterate test

    - Extract function

    - Assert with regex expression

    - Repeat N times

      The code in the code editor automatically changes to show the selected example code.

3.  Modify the example test for your own needs. See
    [BDD Test-Writing Syntax Reference](https://docs.mulesoft.com/api-functional-monitoring/bat-bdd-reference) to understand the syntax and write your
    own tests.

4.  Validate whether the test works by clicking **Validate Test**.

> [!NOTE] The example menu is available only when creating a monitor.

## See Also

- [The website for the Deck of Cards API](https://deckofcardsapi.com/)

- [BDD Test-Writing Syntax Reference](https://docs.mulesoft.com/api-functional-monitoring/bat-bdd-reference)

- [Creating Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor)

- [Modifying Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-modify-monitor)

<!-- document id=63657b683614862e572fe47a7c13afe448574848ecfde869a30470e3621aa8f3 url=/mulesoft/current/en-us/api-functional-monitoring/bat-install-task.md -->

---
product: API Functional Monitoring
---

# Installing BAT

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The Blackbox Automated Testing (BAT) CLI wrapper is a command line wrapper that you install to
execute API tests.

## Prerequisite for Linux and macOS Systems

Before installing BAT CLI, ensure that Java 17 is installed:

```shell
java -version
```

## Prerequisites for Windows 10 Systems

1.  Install Windows Subsystem for Linux (WSL)

    The instructions are at
    [https://learn.microsoft.com/en-us/windows/wsl/install](https://learn.microsoft.com/en-us/windows/wsl/install).

2.  Install Java 17, curl, and the application "unzip" into the Linux distribution that you
    installed in your WSL.

3.  Ensure that the `JAVA_HOME` variable in your environment is set to the location of your Java
    installation.

4.  Add the `bat` executable to your `PATH` environment variable:

    1.  Open the `~/.bashrc` file (if you are using `bash`) or the `~/.zshrc` file (if you are using
        `zsh`) for editing. For example, to use the `vi` editor, enter either of these commands:

        `vi ~/.bashrc`

        `vi ~/.zshrc`

    2.  Add the following line to the end of the file and then save the file:

        `export PATH=$PATH:~/.bat/bat/bin`

## Install BAT

You can install BAT CLI on Linux, macOS, and Windows.

### Linux and macOS Systems

1.  [Download the BAT CLI ZIP file](https://repository-master.mulesoft.org/nexus/content/repositories/releases/com/mulesoft/bat/bat-wrapper/1.1.14/bat-wrapper-1.1.14.zip)
    and save it in your `Downloads` directory.

2.  Open a terminal and run the following command to install BAT CLI:

    ```shell
    BAT_ZIP="$(ls -t "$HOME"/Downloads/bat-wrapper*.zip 2>/dev/null | head -n 1)"
    if [ -z "$BAT_ZIP" ]; then
      echo "BAT CLI ZIP file was not found in the Downloads directory."
    else
      mkdir -p "$HOME/.bat"
      unzip -o "$BAT_ZIP" -d "$HOME/.bat"
      chmod +x "$HOME/.bat/bat/bin/bat"
    fi
    ```

    The command selects the most recently downloaded BAT CLI ZIP file and installs it under
    `$HOME/.bat`.

3.  Add BAT CLI to your `PATH`.

    Identify your default shell:

    ```shell
    basename "$SHELL"
    ```

    - If the command displays `zsh`, run:

      ```shell
      echo 'export PATH="$HOME/.bat/bat/bin:$PATH"' >> "$HOME/.zshrc"
      . "$HOME/.zshrc"
      ```

    - If the command displays `bash`, run:

      ```shell
      echo 'export PATH="$HOME/.bat/bat/bin:$PATH"' >> "$HOME/.bashrc"
      . "$HOME/.bashrc"
      ```

    - If a different shell is displayed, add `$HOME/.bat/bat/bin` to the startup file used by that
      shell.

4.  Run the following command to verify that BAT CLI is installed:

    ```shell
    bat --version
    ```

    The installation is successful if the command displays the BAT CLI version.

### Windows

1.  Click
    [here](https://repository-master.mulesoft.org/nexus/content/repositories/releases/com/mulesoft/bat/bat-wrapper/1.1.14/bat-wrapper-1.1.14.zip)
    to automatically download the ZIP file of the BAT wrapper for Windows.

2.  Unzip the ZIP file to install BAT CLI in your Windows environment.

3.  Run the command `bat -version` to verify that BAT CLI is installed.

## What to Do Next

You can now start creating a test suite.

## See Also

- [Starting a New Test Suite](https://docs.mulesoft.com/api-functional-monitoring/bat-start-new-project)

- [BAT Command Reference](https://docs.mulesoft.com/api-functional-monitoring/bat-command-reference)

<!-- document id=cd722aad0b19f436cfe8c0d5845c99feba0bfc63d25753b1e698c2483fda2200 url=/mulesoft/current/en-us/api-functional-monitoring/afm-modify-monitor.md -->

---
product: API Functional Monitoring
---

# Modifying Monitors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can modify monitors in API Functional Monitoring, which includes the options to edit the monitor
as text fields or to edit the monitor as BAT source. Additionally you can download the monitor as
BAT source, edit the monitor in your text editor of choice, and then upload the monitor. You can
modify a monitor from either the homepage or the monitor’s detail page.

## Before You Begin

Ensure that you have the following permissions set in Access Management:

- **Anypoint Monitoring > Viewer** or **Anypoint Monitoring > Administrator**

  and

- **Exchange > Exchange Administrator** or **Exchange > Exchange Contributor**

An Anypoint Platform administrator for your organization grants permission. See
[Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions).

## Modify a Monitor from the Home Page

To modify a monitor from the homepage:

1.  Hover over the name of the monitor you want to modify.

2.  Click **Edit** (![afm ui edit button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-edit-button.png)).

## Modify a Monitor from its Details Page

To modify a monitor from its detail page:

1.  Select the monitor that you want to modify.

2.  Click **More** (![afm ui more button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-more-button.png)) next to the monitor name.

3.  Click **Edit Monitor**.

You can edit the endpoints' **Validate SSL Certificate** toggle setting, methods, URLs, optional
headers, and assertions. See [Creating Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor) for more detail on the fields.

Click **Switch to code editor** to edit the monitor as BAT source. For more details, see
[BDD Test-Writing Syntax Reference](https://docs.mulesoft.com/api-functional-monitoring/bat-bdd-reference).

## See Also

- [Creating Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor)

- [Downloading Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-download-test)

- [Uploading Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-upload-monitor)

<!-- document id=71ff7a339bdc64a9d742911da4deab79fc658075bf021adf50940eb6a386c8f7 url=/mulesoft/current/en-us/api-functional-monitoring/afm-modify-schedule.md -->

---
product: API Functional Monitoring
---

# Modifying Schedules

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can modify a schedule to change:

- The location at which the test is run

- The frequency at which to run the test

## Before You Begin

- Before you run a schedule in a public location, ensure that your Anypoint Platform organization
  has not reached its maximum number of schedules. When you attempt to create a new monitor, a
  message displays if no public schedules are available.

- Ensure that your user ID has the following permission set in Access Management:

  - **Exchange > Exchange Administrator** or **Exchange > Exchange Contributor**

An Anypoint Platform administrator for your organization grants permission. See
[Manage Permissions](https://docs.mulesoft.com/access-management/managing-permissions).

## Modify a Schedule

Modify a schedule either from the **Schedules** section of a monitor, or from the schedules list.

To modify a schedule from the **Schedules** section of a monitor:

1.  Select the monitor in which you want to modify a schedule.

2.  Find the schedule in the list, click **More**
    (![afm ui more button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-more-button.png)), and select **Modify Schedule**.

3.  In the **Modify Schedule** dialog, change one or more of the following:

    - The location at which to run the test

    - The frequency at which to run the test

4.  Click **Save**.

To modify a schedule from the schedules list:

1.  Display the list of locations by opening the **Locations manager** dialog in the homepage.

2.  Select the location in which the schedule is running.

3.  Find the schedule in the list, click **More**
    (![afm ui more button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-more-button.png)), and select **Modify Schedule**.

4.  In the Modify Schedule dialog, change one or more of these items:

    - The frequency at which to run the test

    - The configuration to run the test

5.  Click **Save**.

    Changes take place after the current interval elapses. For example, if you change the interval
    of a schedule from every 15 minutes to every hour and the timer on the monitor shows that there
    are 5 minutes remaining in the current interval, the new interval goes into effect after the
    five minutes elapse and the test is run.

## See Also

- [Scheduling Testing and Monitoring](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-test-task)

- [Managing Permissions](https://docs.mulesoft.com/access-management/managing-permissions)

<!-- document id=f764c579ebd8152550998802f849817f3ddd36eacef49af8f716aab1d7884789 url=/mulesoft/current/en-us/api-functional-monitoring/afm-monitoring-private-apis.md -->

---
product: API Functional Monitoring
---

# Monitoring the Endpoints of Private APIs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!IMPORTANT] API Functional Monitoring now supports Mule Runtime 4.9 LTS (Java 17). You can now
> upgrade your private monitoring locations to version 4.9.

API Functional Monitoring (AFM) lets you monitor private APIs if you have a subscription to Anypoint
Virtual Private Cloud (Anypoint VPC).

Private APIs are APIs with endpoints that are accessible only within your network inside an Anypoint
VPC.

A private location is a Mule application that runs in an environment in CloudHub 1.0 or Cloudhub
2.0. You can run tests against APIs that are accessible only within the private location. The
private location environment might have an Anypoint VPC associated with it. You can create multiple
private locations in a single instance of Anypoint VPC.

To test private endpoints, use the internal URLs of the applications. These are the internal/VPC IP
addresses of the Mule workers, in the form of `mule-worker-internal-myapp.region.cloudhub.io`. The
VPC must also have access to the applications' ports. See the
[CloudHub Networking Guide](https://docs.mulesoft.com/cloudhub/cloudhub-networking-guide).

> [!NOTE] You can also test public APIs using private locations. Public APIs are APIs with endpoints
> that are exposed to the internet.

## Association of Private Locations with Schedules

When you use private locations, you can run as many workers as your allotment of vCores allows. By
default, each worker consumes 0.2 vCores. Therefore, MuleSoft does not limit the number of schedules
that you can create for tests that are run from private locations.

Also, you can run tests from private locations with intervals of five minutes.

## Creation of Private Locations

Before you can run tests of private APIs from a private location, you must create a private
location, which involves specifying a name and an environment for the worker to run in. The
environment must be associated with an instance of Anypoint VPC and must be the same environment
that an API to be tested is deployed in. For example, you might create a private location that you
name `myLocation` and set it to run in environment `myEnvironment`. When you choose to run a test in
`myLocation`, AFM allocates a worker in `myEnvironment` in Anypoint Virtual Private Cloud.

> [!IMPORTANT] In early versions of private locations, for tests to run, you had to allow incoming
> HTTP traffic into the private location’s environment. If you
> [update your private location](#update-private-locations), you no longer need to allow incoming
> HTTP traffic.

## Possible Test Configurations

The following diagram depicts the types of relationships that monitors of private APIs can have with
their schedules, public locations, APIs, and environments. Each type of relationship is indicated
with a unique line style.

![afm private locations](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-private-locations.png)

1.  Monitor 1’s relationships (indicated with solid black arrows): single schedule, single location,
    single environment

    Monitor 1 runs on a single schedule, Schedule A. The schedule is associated with Private
    Location 1. The monitor is written to test one or more endpoints in Private API 1 and in Private
    API 2, although it could also test endpoints in more private APIs. The private location and APIs
    are in a single environment, environment A.

2.  Monitor 2’s relationships (indicated with dashed green arrows): multiple schedules, single
    location, single environment

    Monitor 2 runs on two separate schedules, Schedule B and Schedule C, and each is associated with
    the same private location, Private Location 1. The private location is shared with the schedule
    that runs Monitor 1. Monitor 2 is written to test one or more endpoints in private API 3 and in
    private API 4, although it could also test endpoints in more private APIs. The private locations
    and APIs are in a single environment, environment A.

3.  Monitor 3’s relationships (indicated with dashed-and-dotted light blue arrows): multiple
    schedules, multiple locations, single environment

    Monitor 3 runs on two separate schedules, Schedule D and Schedule E, and each is associated with
    a different private location, Private Location 2 and Private Location 3. Monitor 3 is written to
    test one or more endpoints in API 5 and in API 6, although it could also test endpoints in more
    private APIs. The private locations and APIs are in a single environment, environment A.

4.  Monitor 4’s relationships (indicated with dotted orange arrows): multiple schedules, multiple
    environments

    Monitor 4 runs on two separate schedules, Schedule F and Schedule G, and each is associated with
    a different private location. Private Location 4 and Private API 7 are in Environment A and
    Private Location 5 and Private API 8 are in Environment B. One environment could be a test
    environment, and the other environment could be a production environment, where Private API 7
    and Private API 8 are copies of the same API. Monitor 4 is written to test one or more endpoints
    in Private API 7 and the same endpoints in Private API 8, although it could also test endpoints
    in more private APIs.

5.  Monitor 5’s relationships (indicated with solid violet arrows): tests private and public APIs

    Monitor 5 runs on one schedule, Schedule H, although it could run on multiple schedules. The
    schedule is associated with a private location, Private Location 5. Monitor 5 is written to test
    one or more endpoints in Private API 9 and in Public API 10. Private Location 5 and Private API
    9 are in Environment B, and Public API 10 is on the web.

## Length of Time Before Tests Time Out

When tests are run by private locations in an instance of Anypoint VPC, the workers do not share
resources with other MuleSoft customers. Therefore, AFM allows tests to wait for a default of thirty
minutes for a response from an endpoint. You can increase this time in Anypoint Runtime Manager. To
do so, follow these steps:

1.  Go to Anypoint Runtime Manager.

2.  Open the settings for the private location for which you want to increase the timeout.

3.  In the **executionTimeout** field, specify a longer timeout in milliseconds.

## Update Private Locations

As updates become available, you are notified in the **Locations** modal dialog. Follow the prompts
to apply the update to all private locations.

### Mule Runtime Compatibility

Private locations run on a Mule Runtime version that you manage. To maintain security and support,
ensure your private locations run on a supported Long-Term Support (LTS) version:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Runtime Version</th><th>Status</th><th>Action Required</th></tr></thead><tbody><tr><td><p>Mule 4.9 LTS (Java 17)</p></td><td><p>Supported</p></td><td><p>No action required</p></td></tr><tr><td><p>Mule 4.6 LTS</p></td><td><p>Supported</p></td><td><p>Plan upgrade to 4.9 before end of support</p></td></tr><tr><td><p>Mule 4.4 LTS</p></td><td><p>End of Life — no longer supported</p></td><td><p>Upgrade to 4.6 or 4.9 immediately</p></td></tr></tbody></table>

If your private locations run on Mule Runtime 4.4, upgrade to 4.6 or 4.9 as soon as possible.
Running monitors on an EOL runtime poses security risks and is not supported.

After upgrading, validate your private location’s compatibility within your VPC and security
configuration. See [Creating Private Locations](https://docs.mulesoft.com/api-functional-monitoring/afm-create-private-location).

## See Also

- [Scheduling Testing and Monitoring](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-test-task)

<!-- document id=e3904cfbd41913ac5189e32611c369332a6ef337bf3ba16c37d00b4f560d4154 url=/mulesoft/current/en-us/api-functional-monitoring/afm-monitoring-public-apis.md -->

---
product: API Functional Monitoring
---

# Monitoring the Endpoints of Public APIs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Public APIs are APIs with endpoints that are exposed to the public internet. Tests of such endpoints
are run by workers that themselves run in public locations or private locations.

A public location is a region, or resource pool, that is shared with other MuleSoft customers.
Examples of such regions are `us-east-1`, `us-east-2`, and `eu-central-1`.

For information about private locations, see
[Monitoring the Endpoints of Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-private-apis).

The tests in monitors are run on schedules. For a worker to run in a public location according to a
schedule, a schedule must be associated with it. A public location can be associated with more than
one schedule for more than one monitor.

The following diagram depicts the types of relationships that monitors of public APIs can have with
their schedules, public locations, APIs, and environments. Each type of relationship is indicated
with a unique line style.

![afm public locations](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-public-locations.png)

1.  Monitor 1’s relationships (indicated with solid black arrows): single schedule, single location,
    single environment

    Monitor 1 runs on a single schedule, Schedule A, which is associated with Public Location 1. The
    monitor is written to test one or more endpoints in public API 1 and public API 2, although it
    could also test endpoints in more public APIs. The two APIs are in a single environment,
    environment A.

2.  Monitor 2’s relationships (indicated with dashed green arrows): multiple schedules, single
    location, single environment

    Monitor 2 runs on two separate schedules, Schedule B and Schedule C, each of which is associated
    with the same public location, Public Location 1. Monitor 2 is written to test one or more
    endpoints in public API 3 and public API 4, although it could also test endpoints in more public
    APIs. The two APIs are in a single environment, Environment A.

3.  Monitor 3’s relationships (indicated with dashed-and-dotted light blue arrows): multiple
    schedules, multiple locations, single environment

    Monitor 3 runs on two separate schedules, Schedule D and Schedule E, each of which is associated
    with a different public location, Public Location 1 and Public Location 2. Monitor 3 is written
    to test one or more endpoints in public API 5 and public API 6, although it could also test
    endpoints in more public APIs. The two APIs are in a single environment, Environment A.

4.  Monitor 4’s relationships (indicated with dotted orange arrows): multiple schedules, multiple
    environments

    Monitor 4 runs on two separate schedules, Schedule F and Schedule G. Each of the schedules is
    associated with the same public location, Public Location 2, although each could be associated
    with a different public location. Each of the two tested public APIs is in a different
    environment, Environment A and Environment B. One environment could be a test environment, and
    the other environment could be a production environment, where public API 7 and public API 8 are
    copies of the same API. Monitor 4 is written to test one or more endpoints in public API 7 and
    the same endpoints in public API 8, although it could also test endpoints in more public APIs.

5.  Monitor 5’s relationships (indicated with dashed dark blue arrows): tests APIs in CloudHub 1.0
    environments and on the web

    Monitor 5 runs on a single schedule, Schedule H, although it could run on multiple schedules.
    The schedule is associated with Public Location 2. Monitor 5 is written to test one or more
    endpoints in public API 9 and in public API 10, although it could also test endpoints in more
    public APIs. Both APIs are accessible on the web.

## Testing Private APIs from Public Locations

You can test private APIs from public locations if you allow the IP addresses of those locations.
You can test a private API from a public location if you don’t want to use vCores for testing
private APIs, or if you have no vCores available.

In Runtime Manager, add a new rule to the firewall for Anypoint Virtual Private Cloud (Anypoint
VPC). The type must be **https.port**, the source must be **Custom**, and the port range 8081. For
the source, use one of the following IP addresses:

<table><colgroup><col> <col></colgroup><thead><tr><th>Public Location</th><th>IP Address</th></tr></thead><tbody><tr><td><p>us-east-1</p></td><td><p>3.82.89.58</p></td></tr><tr><td><p>us-east-2</p></td><td><p>3.128.151.139</p></td></tr><tr><td><p>eu-central-1</p></td><td><p>18.156.106.167</p></td></tr></tbody></table>

For instructions on adding firewall rules, refer to
[VPC Firewall Rules](https://docs.mulesoft.com/cloudhub/vpc-firewall-rules-concept)

## Length of Time Before Tests Time Out

To prevent tests run in public locations from consuming too many resources, AFM prevents tests from
executing for more than 120 seconds. A test fails if this maximum length of time is reached. You
cannot increase this wait time.

## Scheduling Tests

Tests are run at fixed intervals that you define in schedules. Each test is associated with a
schedule. When you run tests from public locations, AFM sets limits on the following aspects of
scheduling:

- **Number of Schedules**: By default, your organization can run up to five schedules simultaneously
  for testing from public locations. If you reach the limit of five schedules and want to run more
  monitors simultaneously, contact your MuleSoft Customer Success Manager about raising your
  maximum.

- **Duration of Intervals Between Executions of Tests**: You can schedule test intervals using a
  cron expression. The minimum duration of intervals between tests is set by account type. See
  [Limits for Schedule Intervals by Location](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-test-task#scheduling-limits).

You can also run monitors from private locations if you have access to Anypoint Virtual Private
Cloud. There is no limit to the number of schedules that you can create to use private locations.
For details, see [Monitoring the Endpoints of Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-private-apis).

You can monitor public APIs from private locations, too, not just private APIs.

## See Also

- [Scheduling Testing and Monitoring](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-test-task)

<!-- document id=a94e560dc5837225b612a772316f330c7ca28ffe22d75623cd13e4a75e78ec57 url=/mulesoft/current/en-us/api-functional-monitoring/bat-execute-task.md -->

---
product: API Functional Monitoring
---

# Run a Test Suite

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using the BAT CLI, you can execute one test at a time or all tests listed in the `bat.yaml` file for
a test suite.

## To Run Tests

- To run all of the tests that are listed in the `bat.yaml` file for a test suite, run the `bat`
  command at the root level in your test-suite directory. Your `bat.yaml` file for the test suite
  must also be at the root level in this directory.

- To run a single test that is listed in the `bat.yaml` file for a test suite, run the command
  `bat ./folder/file.dwl` at the root level in your test-suite directory:

  `folder`

  Specify the path to the test file.

  `file.dwl`

  Specify the name of the test file.

  Your `bat.yaml` file for the test suite must also be at the root level in the test-suite
  directory.

## What to Do Next

By default in the example test suite that you can generate with the `bat init` command, BAT
generates an HTML report about the test results. The configuration of this report is in the
`reporters` section on the `bat.yaml` file.

\+ .The default configuration of the HTML report

```yaml
reporters:
  - type: HTML
    outFile: /tmp/HTML.html
```

However, you can receive reports of test failures from several supported applications, not just in
an HTMl file. See [Configuring and Viewing Reports](https://docs.mulesoft.com/api-functional-monitoring/bat-reporting-task).

<!-- document id=f9ee02b0b58fef656e9269664e5e25098ef7cec9d16a0e5d9fb6bd0152a8f1b8 url=/mulesoft/current/en-us/api-functional-monitoring/bat-schedule-test-task.md -->

---
product: API Functional Monitoring
---

# Scheduling Testing and Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can schedule, run, and monitor an API test in Anypoint Platform using the default schedule and
use a cron job to change the schedule. BAT is deployed by default in the Production environment of
Anypoint Platform when you execute the `bat login` command. After deploying BAT, you execute a
`bat schedule <options>` command. By default, if you don’t include the optional cron expression in
the command, the test runs every 15 minutes. The last step in this procedure changes the default to
use a cron expression that runs the test once a day for a month.

After running the command, BAT creates a monitor in Anypoint Platform. The monitor collects
information about the scheduled execution of the test. To obtain this information, you need to set
up a third-party reporting tool as described in the linked topic.

To schedule testing and monitoring:

1.  Log in to Anypoint Platform using BAT CLI. For example:

    `bat login --client-id=<value> --client-secret=<value>` or
    `bat login --username=<value> --password=<value>`

2.  Create a schedule using the default and monitor the testing. Provide an arbitrary endpoint URL
    and optionally specify the current directory by using --init-folder to store scheduling
    information. For example:

    `bat schedule endpoint http://www.example.com --init-folder`

    The schedule is published to Exchange using the default login profile.

    Output looks like this in Mac OSX:

    BAT Version: 1.0.51

    # File: ./tests/step.0.dwl

        api-mon
          ✓ GET http://apimon.cloudhub.io/users (1316.85ms)
            ✓ 200 must equal 200

    # File: ./tests/step.1.dwl

    ... ✓ 10 must equal 10

    # Reporter: bat/Reporters/JSON.dwl >> /var/folders/w5/\_cc\_5\_z12pq3qnymf3f0zh840000gq/T/bat\_report\_20180226111256.json

    # Reporter: bat/Reporters/HTML.dwl >> /var/folders/w5/\_cc\_5\_z12pq3qnymf3f0zh840000gq/T/bat\_report\_20180226111256.html

    #Creating artifact...
    - exchange.json
    - .DS\_Store
    - tests/step.0.dwl
    - tests/step.1.dwl
    - main.dwl
    - bat.yaml

    # Creating artifact...OK

    # Uploading 88f362bd-2092-4dbf-b9f2-db5624d7b4ab:www.telhill.com-ncQRvDwc:0.0.1

    # Version 0.0.1 published

    scheduleId: 99c24a04-b82b-4366-b02b-4682fa405ead

3.  Go to the path for one of the local reporters listed in the output to see information about the
    executed test. For example, on Mac OSX, go to
    `/var/folders/w5/_cc_5_z12pq3qnymf3f0zh840000gq/T/bat_report_20180226111256.html`.

4.  Go to Exchange and view the asset named after the monitor URL that you provided in the
    `bat schedule endpoint` command. It is `http://www.example.com` in this example.

5.  List the schedule of tests.

    `bat schedule list [--profile=<value>]`

6.  Schedule a test to run repeated using a cron expression. For example, run the test at 12:00 PM
    every day for one month:

    `bat schedule create --cron="0 0 12 1/1 * ? *"`

Next, configure and view test reports.

## Limits for Schedule Intervals by Location

The minimum interval for schedules that run in private locations is always five minutes.

The minimum interval for schedules that run in public locations depends on the number of schedule
entitlements, or API monitor entitlements, that you have. If you have more than five, the limit is
five minutes. Otherwise, it is fifteen minutes.

The limit depends on the type of location, not on whether the API is public or private, because you
can test a public API from a private location.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Location Type</th><th>Number of Entitlements</th><th>Account Type</th><th>Interval Time Allowed</th></tr></thead><tbody><tr><td><p>Public</p></td><td><p>5 or less</p></td><td><p>Developer</p></td><td><p>15 minutes</p></td></tr><tr><td><p>Public</p></td><td><p>5 or less</p></td><td><p>Other</p></td><td><p>15 minutes</p></td></tr><tr><td><p>Public</p></td><td><p>More than 5</p></td><td><p>Developer</p></td><td><p>15 minutes</p></td></tr><tr><td><p>Public</p></td><td><p>More than 5</p></td><td><p>Other</p></td><td><p>5 minutes</p></td></tr><tr><td><p>Private</p></td><td><p>Any number</p></td><td><p>N/A</p></td><td><p>5 minutes</p></td></tr></tbody></table>

## See Also

- [Configuring and Viewing Reports](https://docs.mulesoft.com/api-functional-monitoring/bat-reporting-task)

- [BAT CLI Reference](https://docs.mulesoft.com/api-functional-monitoring/bat-command-reference)

- [Monitoring the Endpoints of Public APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-public-apis)

<!-- document id=f1f8e171cabb1dc6b7e1df1deb33d29592f26405d284ad1b2f7176a6825b6345 url=/mulesoft/current/en-us/api-functional-monitoring/bat-start-new-project.md -->

---
product: API Functional Monitoring
---

# Starting New Test Suites

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Starting a new test suite for testing API endpoints involves only a few steps to create and populate
with initial lines a file named `bat.yaml`. This file explains the structure of your test suite to
the BAT CLI.

## Start a New Test Suite

1.  Create a directory in your computer’s filesystem.

2.  Change to the new directory.

3.  Create a file named `bat.yaml`.

4.  Open the file for editing.

5.  Add these five lines to specify the name of the test suite:

    ```yaml
    suite:
      name: "name_of_suite_of_tests"

    files:
    ```

    name\_of\_suite\_of\_tests

    Specify the name that you want to give the suite of tests that you plan to write.

6.  Save the file.

7.  Create a folder in your directory in which to create tests.

    You can give the folder any name.

8.  Optional: Create a folder named `config`.

    In this folder, you create configuration files to use for your tests. Configuration files
    contain variables that are injected to tests at runtime. You can refer to those variables in
    tests by using the `config` variable.

    For example, to refer to a variable named `url` in a configuration file, you use this reference:
    '$(config.url)'. When you run the `bat` command to execute a test, you specify the configuration
    file to use by including the `--config=file.dwl` option, where `file.dwl` is the path and name
    of the configuration file in the folder for your test suite.

## What to Do Next

You can start writing tests.

## See Also

- [Example of a Test Suite](https://docs.mulesoft.com/api-functional-monitoring/bat-example-test-suite)

<!-- document id=5e31e2541d48bcac1047a909b1b59b25fae04444093490d5c5c56e85caa0b3c2 url=/mulesoft/current/en-us/api-functional-monitoring/afm-upload-monitor.md -->

---
product: API Functional Monitoring
---

# Uploading Monitors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upload a suite of tests that you have written and want to run as a monitor, viewing the
results the information displays in the **Functional Monitoring** section of Anypoint Monitoring.
When you create monitors by writing them, you can create more complex test cases by using features
such as the DataWeave expression language and context variables for saving values between calls to
endpoints.

## Before You Begin

- Ensure that your user ID has the Monitoring Center User permission. An administrator for your
  organization can grant you this permission in Anypoint Access Management.

- Write a suite of tests in the BDD test-writing language. For information about writing tests, see
  [API Functional Monitoring with BAT CLI](https://docs.mulesoft.com/api-functional-monitoring/bat-top).

- Determine the frequency at which you would like the monitor to endpoints in the test suite. The
  shortest interval is every fifteen minutes. You can also choose to run the monitor hourly, daily,
  weekly, or monthly. The schedule begins immediately after you upload the monitor. After you upload
  the monitor, you can create another schedule that is more detailed, if you prefer.

- Determine which execution location you would like to run the monitor in.

- If you have more than one configuration file in your test suite, determine which you plan to use
  for the monitor.

## Upload a Monitor

To create a monitor by uploading a test suite:

1.  In the **Functional Monitoring** section of Anypoint Monitoring, click **Upload Monitor**.

2.  Select the folder that contains your test suite.

    For details on file structure and file requirements, see
    [Example of a Test Suite](https://docs.mulesoft.com/api-functional-monitoring/bat-example-test-suite).

3.  Click **Upload Monitor**.

4.  Click **Next**.

    The **Monitor Detail** page opens.

5.  In the **Last executions** list, you can view the test result and how long the test ran.

## What to Do Next

You can view a list of monitor schedules in the schedules table. You can also disable and enable
schedules.

The last executions table and the average times chart enable you to determine:

- Whether the endpoint returned the expected code, as indicated by **PASSED** or **FAILED**

- Statistics about the execution of the endpoint test

As your monitor continues to run at the scheduled intervals, the statistics in this table are
updated, as well as the graph.

## See Also

- [API Functional Monitoring with BAT CLI](https://docs.mulesoft.com/api-functional-monitoring/bat-top)

<!-- document id=01d979a342a2567ba759906a4e74dd6f17bc4af2c701807f96360c2400fc1428 url=/mulesoft/current/en-us/api-functional-monitoring/afm-mask-info-in-monitors.md -->

---
product: API Functional Monitoring
---

# Using Secrets to Mask Sensitive Information in Monitors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

In monitors that you run in a private location, you can mask sensitive information such as headers,
token values, username and password, and body values.

To mask the header information:

1.  [Configure a shared secret](#configure-secret) in Secrets Manager for the information you want
    to mask.

2.  [Modify your monitor](#add-secret-to-monitor) to use the information from Secrets Manager.

3.  [Grant the monitor permission](#grant-access-to-secret) to access the secret, which creates an
    alias for the secret.

4.  To deploy your changes, [upload the modified monitor](#deploy-updated-monitor) to Functional
    Monitoring.

## Limitations

- Functional Monitoring works only with symmetric key shared secret types from Anypoint Secrets
  Monitor.

- You can use aliases for shared secrets in a test suite only if you plan to run that test suite
  from a private location.

## Configure a Secret in Anypoint Secret Manager

To keep sensitive information secret in tests you run from a private location, create a shared
secret in Secrets Manager.

To configure a shared secret:

1.  Open a secrets group or create a new one. Create the group in the same environment that you are
    using in BAT CLI.

    To find out which environment you are using in BAT CLI:

    1.  Run the command `bat whoami`.

        The output has the ID for the environment.

    2.  Run the command `bat environment ls` to list the environments to which you have access.

    3.  Match the ID from the `bat whoami` command with one of the environments listed.

    4.  If you need to switch to the environment that your secrets group is in, run the command
        `bat environment switch name`, where `name` is the name of the environment.

2.  Select **Shared Secret**.

3.  In the **Type** field, select **Symmetric Key**.

4.  In the **Key** field, paste the sensitive information encoded as a Base64 string.

5.  Paste the Base64 string into the **Confirm Key** field.

## Add the Secret to Your Monitor

Modify your monitor to use the information you configured in Secrets Manager.

To add the secret to a monitor:

1.  Create or download a monitor. See [Creating Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-create-monitor) or
    [Downloading Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-download-test).

2.  Modify the `main.dwl` file to replace the sensitive information with the client ID and client
    secret you configured in Secrets Manager.

    In the following example, the sensitive information in headers are masked. The 'clientId-alias'
    and 'clientSecret-alias' are aliases for the secrets stored in Secrets Manager. See
    [Grant Your Monitor Access to the Secret](#grant-access-to-secret) to learn how to generate the
    alias.

    import \* from bat::BDD import \* from bat::Assertions

    var cliId = secret('clientId-alias') default 'Client Not Found' var cliSecret =
    secret('clientSecret-alias') default 'Secret Not Found'

    suite("HTTP Monitor") in \[ it should "Assert endpoint:
    http://status-coder.ir-e1.cloudhub.io/status?code=200&reason=Ok"" in \[ GET
    \`http://status-coder.ir-e1.cloudhub.io/status?code=200&reason=Ok\` with { "headers": {
    "client\_id": cliId, "client\_secret": cliSecret } } assert \[ $.response.status mustEqual 200
    \] \] \]

After you modify the monitor’s `main.dwl` file to add the secret information to the code, grant the
monitor access to the secrets you configured in Secrets Manager. See
[Grant Your Monitor Access to the Secret](#grant-access-to-secret).

## Grant Your Monitor Access to the Secret

After you modify your monitor to add the secret information, grant the monitor access to the secret.
At runtime, BAT CLI looks up the shared secrets using the aliases.

To grant a monitor access to the secret:

1.  Copy the name of the new shared secret obtained in
    [Configure a Secret in Anypoint Secret Manager](#configure-secret).

2.  At a command prompt, run the `bat grant` command, specifying an alias for the shared secret.
    When you run this command, BAT CLI creates a section named `secrets` in your test suite’s
    `bat.yaml` file, if the section does not already exist. In that section, BAT CLI adds these
    indented lines:

    alias: secretId: "secret-ID"

    - `alias`: The alias that you specified in the `bat grant` command.

    - `secret-ID`: The ID of the secret within Anypoint Secrets Manager. This ID does not appear in
      ASM, so there is no way for someone looking in your `bat.yaml` file to associate the ID with
      any particular secret. The BAT CLI uses this ID to look up the secret that you associated with
      the alias.

## Deploy the Updated Monitor

After completing the prior procedures, upload your monitor as documented in
[Upload a Monitor](https://docs.mulesoft.com/api-functional-monitoring/afm-upload-monitor#upload-a-monitor).

<!-- document id=7cdff411d5268c79277ec38337647fbc07e1c81e2e3ea524214e86023e26ba4c url=/mulesoft/current/en-us/api-functional-monitoring/afm-version-monitors.md -->

---
product: API Functional Monitoring
---

# Versioning Monitors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Although you cannot directly version monitors, you can use schedule rules to specify versions. If
you were using an earlier version of API Functional Monitoring where tests were versioned, your test
version information is preserved, although it is displayed differently. Multiple test versions that
were migrated are now schedules of a single monitor.

To use the version information you had in the earlier version:

1.  Navigate to the old layout.

2.  Download a version of a test that should be preserved.

3.  Unzip the test package.

4.  Upload the unzipped directory.

5.  Choose a new test name.

6.  Specify a schedule rule that corresponds with the test version in the first step.

7.  Delete the version downloaded in the first step.

<!-- document id=c30e4c42efcf2f0c5fdf5bcacfcc5b5026876a9e35f3b7d0d01761cceb55535c url=/mulesoft/current/en-us/api-functional-monitoring/afm-view-schedules-private-location.md -->

---
product: API Functional Monitoring
---

# Viewing Schedules That Use a Private Location

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can view the number of schedules that use a private location.

When initially specifying the private location, a test run worker associated with the schedule is
created in that location. Viewing the location shows how many workers are running.

## View the Schedules That Use a Private Location

1.  Display the list of locations by opening **Location Manager** from the homepage.

2.  Click the **Private Locations** tab.

3.  Select a private location.

    The list of schedules that use the private location appears. Each schedule displays the
    following information:

    - The name of the monitor that the test is defined in

    - The interval at which the test is run

    - The configuration used when running the test

<!-- document id=660df4915c54d06ee6dafc26cd6a4366deda929662be2d97365219ec46014643 url=/mulesoft/current/en-us/api-functional-monitoring/afm-view-test-history.md -->

---
product: API Functional Monitoring
---

# Viewing Test History

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can review the details of past test runs.

## View Test History

1.  Select the monitor for which you want to view test results.

2.  Click **View Monitor History** (![afm ui history button](/mulesoft/current/en-us/api-functional-monitoring/_images/afm-ui-history-button.png)) to
    view a list of recent test runs.

    The **History** page is opened for the test. The page displays the status of each execution as
    well as the following associated statistics:

    - The number of endpoints passed from the total number of endpoints tested

    - How long the execution lasted

    - The configuration associated with the execution

    - When the test was last executed

    - The location from which the test was run

3.  Click an execution to see extra information for each tested endpoint:

    - The status of the test

    - The amount of time since the test was executed

    - The type of request

    - The headers in the request

    - The headers in the response

    - The results of the test assertions

## Download Test History

You can download the `result.json` file that contains the full execution information.

<!-- document id=5a972353cc5f7911e93d076b6ebec7cd865d772720f063873b36d89c4f7560b5 url=/mulesoft/current/en-us/api-functional-monitoring/bat-intellij-idea.md -->

---
product: API Functional Monitoring
---

# Writing and Running BAT Tests in IntelliJ IDEA

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can write and run BAT tests in IntelliJ IDEA. The DataWeave 2.0 Intellij plugin, which adds the
required support, offers these features:

- Support for local refactoring

- Syntax highlighting

- A view of the structure of the BAT test that you are editing

- MULE XML language injection

- String interpolation

- Support for running tests

## About This Task

The steps in this procedure explain how to modify a BAT project for support in IntelliJ IDEA, open
that project, create a new test file, and run a test.

## Before You Begin

- Ensure that the DataWeave 2.0 IntelliJ plugin in installed in your IntelliJ IDEA editor. You can
  install it by following these steps:

  1.  In IntelliJ IDEA, open the preferences.

  2.  Select **Plugins** and then click **Browse Repositories**.

  3.  Click **Manage Repositories**.

  4.  Click the plus icon to add a custom repository.

  5.  Paste in the following URL:
      [https://plugins.jetbrains.com/plugins/list?channel=Develop&pluginId=10362](https://plugins.jetbrains.com/plugins/list?channel=Develop&pluginId=10362)

  6.  Click **Check Now** to verify that the repository is reachable. Then, click **OK**.

  7.  In the **Browse Repositories** dialog, search on `dataweave`.

  8.  Select **DataWeave 2.0 IntelliJ Plugin** and then click **Install** in the plugin details.

  9.  Restart IntelliJ IDEA.

- Log in to BAT in a terminal window and run the `bat --update` command to be sure that you have the
  latest version of the BAT CLI.

## Write and Run BAT Tests in IntelliJ IDEA

1.  If you do not already have a BAT project that you want to work with, create one with the
    `bat init` command in a terminal window.

2.  Inside the project folder, run the command `bat idea`.

    **Result**: The command creates a new file in the project: `_project-name_.iml`

3.  In IntelliJ IDEA, open the project by selecting the project folder.

4.  In the **Project Structure** dialog, set the Java SDK that you want to use for your project.

5.  If you want to write a test, create a new test file:

    1.  Right-click the folder that contains your tests and select **New** > **DataWeave
        Component**.

    2.  In the dialog box, select **Bat Test** in the **Kind** field.

    **Result**: A new Bat Test file appears in the Tests folder. Double-click that to open it in the
    editor pane. Write your test in that file.

6.  To run a test:

    1.  Open the test in the editor.

    2.  Right-click in the file and select **Run** > **Bat Test _filename_**.

    **Result**: The output of the test appears in the **Run** tool window.