Contact Free trial Login

BAT CLI Reference

The BAT 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. The BAT CLI is integrated with Anypoint Platform.

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

bat Command

The bat command provides an API Functional Monitoring command line interface.

Syntax

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

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

This option displays an interactive command for the password.

password for user [username]: <password>

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

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 the desired folder. BAT searches for and executes the bat.yaml and main.dwl files.

  • bat ./folder/file.dwl
    Executes 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.

Command Line Options

  • --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.

This command line also offers cloud integration, and to schedule and configure tests and monitors using the 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 that includes the tests and all the files. By default, if a cron expression is not entered, tests are scheduled to run every 15 minutes.

  • schedule endpoint <arbitrary-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 of using an arbitrary URL, for example 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. If you run bat schedule ls after you run this command, you will see that the value

  • 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. Requires a subscription to Anypoint VPC. See Monitoring the Endpoints of Public APIs and Monitoring the Endpoints of Private APIs for more information about private locations 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 lastest 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 currently 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 currently 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 will be 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

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub