Botium Connector for Amazon Alexa Skills API

This is a Botium connector for testing your Amazon Alexa Skills with the Skills Management API.

Did you read the Botium in a Nutshell articles ? Be warned, without prior knowledge of Botium you won't be able to properly use this library!

How it works ?

The Alexa Skills Management API enables Botium to talk to your Alexa skill.

It can be used as any other Botium connector with all Botium Stack components:

• Botium CLI
• Botium Bindings
• Botium Box

Requirements

• Node.js and NPM
• an Alexa Skill, and user account with development rights
• a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Amazon Alexa Skills API Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-alexa-smapi
> botium-cli init
> botium-cli run

When using Botium Bindings:

> npm install -g botium-bindings
> npm install -g botium-connector-alexa-smapi
> botium-bindings init mocha
> npm install && npm run mocha

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting Amazon Alexa Skills API to Botium

This connector includes a CLI wizard to initialize the botium.json file holding your connection credentials.

This wizard is part of Botium CLI as well.

> npx botium-connector-alexa-smapi-cli init

This wizard will guide you through the Botium Connector setup. Please follow the instructions. It involves Copy&Paste from a web browser to this terminal window.

Adapt botium.json

Open the file botium.json in your working directory and add other settings if required.

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "alexa-smapi",
      "ALEXA_SMAPI_API": "invocation",
      "ALEXA_SMAPI_SKILLID": "..."
    }
  }
}

Botium setup is ready, you can begin to write your BotiumScript files.

Extracting Test Cases from the Alexa Interaction Model

This connector provides a CLI interface for importing the Interaction Model from your skill and convert it to BotiumScript.

• Intents and Utterances are converted to BotiumScript utterances files
• Slots are filled with meaningful samples if possible ** You can hand over the samples to use with the --slotsamples switch ** For default slot types, samples are loaded automatically from the official documentation ** For custom slot types, the samples from the interaction model are used

You can either run the CLI with botium-cli (it is integrated there), or directly from this connector (see samples/cli directory for some examples):

> npx botium-connector-alexa-smapi-cli import --interactionmodel entityresolutionquizdemo.json

Please note that a botium-core installation is required

For getting help on the available CLI options and switches, run:

> npx botium-connector-alexa-smapi-cli import --help

Supported Capabilities

CONTAINERMODE: "alexa-smapi"

Set the CONTAINERMODE capability to alexa-smapi

ALEXA_SMAPI_API

default: "simulation"

Either "simulation" or "invocation" to use the respective Skill Management API

• Skill Simulation API handles plain text input (including intent resolution)
• Skill Invocation API handles structured input (intents and slots, no intent resolution done) and is therefore harder to use than the Simulation API

See the samples directory for configuration and conversation samples.

ALEXA_SMAPI_SKILLID

The Alexa Skill ID

ALEXA_SMAPI_LOCALE

default: "en-US"

The locale used for the simulation / invocation - list of valid locales see here

ALEXA_SMAPI_REFRESHTOKEN

The long-living refresh token. Typically, the refresh token is created with the initialization wizard (see above).

ALEXA_SMAPI_BASE_URL

default: "https://api.amazonalexa.com"

Skill Management API Url

ALEXA_SMAPI_CLIENTID and ALEXA_SMAPI_CLIENTSECRET

From your Amazon Security Profile

ALEXA_SMAPI_VENDORID

Amazon vendor id

ALEXA_SMAPI_ENDPOINTREGION

default: "default"

The AWS Endpoint the Skill is linked to (only required for Skill Invocation API) - see here

ALEXA_SMAPI_INVOCATION_TEXT_INTENT and ALEXA_SMAPI_INVOCATION_TEXT_SLOT

When using the Invocation API, tell Botium to use a special intent and a special slot to hand over the input text (intent resolution is done by Skill itself)

ALEXA_SMAPI_INVOCATION_REQUEST_TEMPLATE

default: the file invocation-request-template.json in this repository

When using the Invocation API, tell Botium to use a special template for the invocation request (JSON formatted).

ALEXA_SMAPI_AUDIO_CAPABILITY and ALEXA_SMAPI_DISPLAY_CAPABILITY

default: false

These will add Audio and Display capabilities when set to true to the invocation request sent to the Skill Management API.

ALEXA_SMAPI_REFRESH_USER_ID

default: false

This only works with the invocation API

This will generate a new userId to send within each different convo.txt file. By default the userId is botium-core-test-user and when generated the user will be botium-core-test-user-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with a randomly generated UUID.

ALEXA_SMAPI_KEEP_AUDIO_PLAYER_STATE

default: false

This only works with the invocation API

If your skill contains audio player responses this will track the changes to the audio player such as the token and the playerActivity and allow you to use intents such as AudioPlayer.PlaybackNearlyFinished and other AudioPlayer intents and get the state back on the response.

ALEXA_SMAPI_SIMULATION_PHRASE

default: empty

This only works with the simulation API

Prepend this phrase to all user utterances