TestAdapter class

Reference

Package:: botbuilder-core

Test adapter used for unit tests. This adapter can be used to simulate sending messages from the user to the bot.

Extends: BotAdapter

Remarks

The following example sets up the test adapter and then executes a simple test:

const { TestAdapter } = require('botbuilder');

const adapter = new TestAdapter(async (context) => {
     await context.sendActivity(`Hello World`);
});

adapter.test(`hi`, `Hello World`)
       .then(() => done());

Constructors

TestAdapter((context: TurnContext) => Promise<void> | ConversationReference, Partial<Activity>, boolean)

Creates a new TestAdapter instance.

Properties

activeQueue	Gets the queue of responses from the bot.
conversation	Gets or sets a reference to the current conversation.
enableTrace	Gets a value indicating whether to send trace activities. Sets a value inidicating whether to send trace activities.
locale	Gets or sets the locale for the conversation.
onTurnError	Gets or sets an error handler that can catch exceptions in the middleware or application. Sets an error handler that can catch exceptions in the middleware or application.
template	`Activity` template that will be merged with all activities sent to the logic under test.

Inherited Properties

BotIdentityKey
ConnectorClientKey
OAuthScopeKey

Methods

addExchangeableToken(string, string, string, string, string)	Adds a fake exchangeable token so it can be exchanged later.
addUserToken(string, string, string, string, string)	Adds a fake user token so it can later be retrieved.
continueConversation(Partial<ConversationReference>, (revocableContext: TurnContext) => Promise<void>)	The `TestAdapter` doesn't implement `continueConversation()` and will return an error if it's called.
createConversation(string, string, string)	Create a ConversationReference.
exchangeToken(TurnContext, string, string, TokenExchangeRequest)	Performs a token exchange operation such as for single sign-on.
getAadTokens(TurnContext, string, string[])	Signs the user out with the token server.
getNextReply()	Dequeues and returns the next bot response from the activeQueue.
getSignInLink(TurnContext, string)	Gets a signin link from the token server that can be sent as part of a SigninCard.
getSignInResource(TurnContext, string, string, string)	Gets a sign-in resource.
getTokenStatus(TurnContext, string, string, any)	Asynchronously retrieves the token status for each configured connection for the given user. In testAdapter, retrieves tokens which were previously added via addUserToken.
getUserToken(TurnContext, string, string)	Retrieves the OAuth token for a user that is in a sign-in flow.
makeActivity(string)	Creates a message activity from text and the current conversational context.
processActivity(string \| Partial<Activity>, (context: TurnContext) => Promise<any>)	Receives an activity and runs it through the middleware pipeline.
send(string \| Partial<Activity>)	Sends something to the bot. This returns a new `TestFlow` instance which can be used to add additional steps for inspecting the bots reply and then sending additional activities.
sendTextToBot(string, (context: TurnContext) => Promise<any>)	Processes a message activity from a user.
signOutUser(TurnContext, string, string)	Signs the user out with the token server.
test(string \| Partial<Activity>, string \| Partial<Activity> \| (activity: Partial<Activity>, description?: string) => void, string, number)	Send something to the bot and expects the bot to return with a given reply.
testActivities(Partial<Activity>[], string, number)	Test a list of activities.
throwOnExchangeRequest(string, string, string, string)	Adds an instruction to throw an exception during exchange requests.

Inherited Methods

continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)	Asynchronously resumes a conversation with a user, possibly after some time has gone by.
continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, string, (context: TurnContext) => Promise<void>)	Asynchronously resumes a conversation with a user, possibly after some time has gone by.
continueConversationAsync(string, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)	Asynchronously resumes a conversation with a user, possibly after some time has gone by.
createConversationAsync(string, string, string, string, ConversationParameters, (context: TurnContext) => Promise<void>)	Creates a conversation on the specified channel.
use((context: TurnContext, next: () => Promise<void>) => Promise<void> \| Middleware[])	Adds middleware to the adapter's pipeline.

Constructor Details

TestAdapter((context: TurnContext) => Promise<void> | ConversationReference, Partial<Activity>, boolean)

Creates a new TestAdapter instance.

new TestAdapter(logicOrConversation?: (context: TurnContext) => Promise<void> | ConversationReference, template?: Partial<Activity>, sendTraceActivity?: boolean)

Parameters

logicOrConversation: (context: TurnContext) => Promise<void> | ConversationReference

The bots logic that's under test.

template: Partial<Activity>

(Optional) activity containing default values to assign to all test messages received.

sendTraceActivity: boolean

Indicates whether the adapter should add to its queue any trace activities generated by the bot.

Property Details

activeQueue

Gets the queue of responses from the bot.

activeQueue: Partial<Activity>[]

Property Value

Partial<Activity>[]

conversation

Gets or sets a reference to the current conversation.

conversation: ConversationReference

Property Value

ConversationReference

enableTrace

Gets a value indicating whether to send trace activities. Sets a value inidicating whether to send trace activities.

boolean enableTrace

Property Value

boolean

A value indicating whether to send trace activities.

locale

Gets or sets the locale for the conversation.

locale: string

Property Value

string

onTurnError

Gets or sets an error handler that can catch exceptions in the middleware or application. Sets an error handler that can catch exceptions in the middleware or application.

(context: TurnContext, error: Error) => Promise<void> onTurnError

Property Value

(context: TurnContext, error: Error) => Promise<void>

A promise representing the async operation.

Remarks

The error handler is called with these parameters:

Name	Type	Description
`context`	TurnContext	The context object for the turn.
`error`	`Error`	The Node.js error thrown.

template

Activity template that will be merged with all activities sent to the logic under test.

template: Partial<Activity>

Property Value

Partial<Activity>

Inherited Property Details

BotIdentityKey

BotIdentityKey: symbol

Property Value

symbol

Inherited From BotAdapter.BotIdentityKey

ConnectorClientKey

ConnectorClientKey: symbol

Property Value

symbol

Inherited From BotAdapter.ConnectorClientKey

OAuthScopeKey

OAuthScopeKey: symbol

Property Value

symbol

Inherited From BotAdapter.OAuthScopeKey

Method Details

addExchangeableToken(string, string, string, string, string)

Adds a fake exchangeable token so it can be exchanged later.

function addExchangeableToken(connectionName: string, channelId: string, userId: string, exchangeableItem: string, token: string)

Parameters

connectionName: string

Name of the auth connection to use.

channelId: string

Channel ID.

userId: string

User ID.

exchangeableItem: string

Exchangeable token or resource URI.

token: string

Token to store.

addUserToken(string, string, string, string, string)

Adds a fake user token so it can later be retrieved.

function addUserToken(connectionName: string, channelId: string, userId: string, token: string, magicCode?: string)

Parameters

connectionName: string

The connection name.

channelId: string

The channel id.

userId: string

The user id.

token: string

The token to store.

magicCode: string

(Optional) The optional magic code to associate with this token.

continueConversation(Partial<ConversationReference>, (revocableContext: TurnContext) => Promise<void>)

The TestAdapter doesn't implement continueConversation() and will return an error if it's called.

function continueConversation(_reference: Partial<ConversationReference>, _logic: (revocableContext: TurnContext) => Promise<void>): Promise<void>

Parameters

_reference: Partial<ConversationReference>

A reference to the conversation to continue.

_logic: (revocableContext: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

A promise representing the async operation.

createConversation(string, string, string)

Create a ConversationReference.

static function createConversation(name: string, user?: string, bot?: string): ConversationReference

Parameters

name: string

name of the conversation (also id).

user: string

name of the user (also id) default: User1.

bot: string

name of the bot (also id) default: Bot.

Returns

ConversationReference

The ConversationReference.

exchangeToken(TurnContext, string, string, TokenExchangeRequest)

Performs a token exchange operation such as for single sign-on.

function exchangeToken(context: TurnContext, connectionName: string, userId: string, tokenExchangeRequest: TokenExchangeRequest): Promise<TokenResponse>

Parameters

context: TurnContext

(xref:botbuilder-core.TurnContext) for the current turn of conversation with the user.

connectionName: string

Name of the auth connection to use.

userId: string

User id associated with the token.

tokenExchangeRequest: TokenExchangeRequest

Exchange request details, either a token to exchange or a uri to exchange.

Returns

Promise<TokenResponse>

If the promise completes, the exchanged token is returned.

getAadTokens(TurnContext, string, string[])

Signs the user out with the token server.

function getAadTokens(_context: TurnContext, _connectionName: string, _resourceUrls: string[]): Promise<[key: string]: TokenResponse>

Parameters

_context: TurnContext

Context for the current turn of conversation with the user.

_connectionName: string

Name of the auth connection to use.

_resourceUrls: string[]

The list of resource URLs to retrieve tokens for.

Returns

Promise<[key: string]: TokenResponse>

A Dictionary of resourceUrl to the corresponding TokenResponse.

getNextReply()

Dequeues and returns the next bot response from the activeQueue.

function getNextReply(): Partial<Activity>

Returns

Partial<Activity>

The next activity in the queue; or undefined, if the queue is empty.

getSignInLink(TurnContext, string)

Gets a signin link from the token server that can be sent as part of a SigninCard.

function getSignInLink(context: TurnContext, connectionName: string): Promise<string>

Parameters

context: TurnContext

Context for the current turn of conversation with the user.

connectionName: string

Name of the auth connection to use.

Returns

Promise<string>

A signin link from the token server that can be sent as part of a SigninCard.

getSignInResource(TurnContext, string, string, string)

Gets a sign-in resource.

function getSignInResource(context: TurnContext, connectionName: string, userId?: string, _finalRedirect?: string): Promise<SignInUrlResponse>

Parameters

context: TurnContext

(xref:botbuilder-core.TurnContext) for the current turn of conversation with the user.

connectionName: string

Name of the auth connection to use.

userId: string

User ID

_finalRedirect: string

Final redirect URL.

Returns

Promise<SignInUrlResponse>

A Promise with a new SignInUrlResponse object.

getTokenStatus(TurnContext, string, string, any)

Asynchronously retrieves the token status for each configured connection for the given user. In testAdapter, retrieves tokens which were previously added via addUserToken.

function getTokenStatus(context: TurnContext, userId: string, includeFilter?: string, _oAuthAppCredentials?: any): Promise<any[]>

Parameters

context: TurnContext

The context object for the turn.

userId: string

The ID of the user to retrieve the token status for.

includeFilter: string

Optional. A comma-separated list of connection's to include. If present, the includeFilter parameter limits the tokens this method returns.

_oAuthAppCredentials: any

AppCredentials for OAuth.

Returns

Promise<any[]>

The TokenStatus objects retrieved.

getUserToken(TurnContext, string, string)

Retrieves the OAuth token for a user that is in a sign-in flow.

function getUserToken(context: TurnContext, connectionName: string, magicCode?: string): Promise<TokenResponse>

Parameters

context: TurnContext

Context for the current turn of conversation with the user.

connectionName: string

Name of the auth connection to use.

magicCode: string

(Optional) Optional user entered code to validate.

Returns

Promise<TokenResponse>

The OAuth token for a user that is in a sign-in flow.

makeActivity(string)

Creates a message activity from text and the current conversational context.

function makeActivity(text?: string): Partial<Activity>

Parameters

text: string

The message text.

Returns

Partial<Activity>

An appropriate message activity.

processActivity(string | Partial<Activity>, (context: TurnContext) => Promise<any>)

Receives an activity and runs it through the middleware pipeline.

function processActivity(activity: string | Partial<Activity>, callback?: (context: TurnContext) => Promise<any>): Promise<any>

Parameters

activity: string | Partial<Activity>

The activity to process.

callback: (context: TurnContext) => Promise<any>

The bot logic to invoke.

Returns

Promise<any>

A promise representing the async operation.

send(string | Partial<Activity>)

Sends something to the bot. This returns a new TestFlow instance which can be used to add additional steps for inspecting the bots reply and then sending additional activities.

function send(userSays: string | Partial<Activity>): TestFlow

Parameters

userSays: string | Partial<Activity>

Text or activity simulating user input.

Returns

TestFlow

a new TestFlow instance which can be used to add additional steps for inspecting the bots reply and then sending additional activities.

Remarks

This example shows how to send a message and then verify that the response was as expected:

adapter.send('hi')
       .assertReply('Hello World')
       .then(() => done());

sendTextToBot(string, (context: TurnContext) => Promise<any>)

Processes a message activity from a user.

function sendTextToBot(userSays: string, callback: (context: TurnContext) => Promise<any>): Promise<any>

Parameters

userSays: string

The text of the user's message.

callback: (context: TurnContext) => Promise<any>

The bot logic to invoke.

Returns

Promise<any>

A promise representing the async operation.

signOutUser(TurnContext, string, string)

Signs the user out with the token server.

function signOutUser(context: TurnContext, connectionName?: string, userId?: string): Promise<void>

Parameters

context: TurnContext

Context for the current turn of conversation with the user.

connectionName: string

Name of the auth connection to use.

userId: string

User ID to sign out.

Returns

Promise<void>

test(string | Partial<Activity>, string | Partial<Activity> | (activity: Partial<Activity>, description?: string) => void, string, number)

Send something to the bot and expects the bot to return with a given reply.

function test(userSays: string | Partial<Activity>, expected: string | Partial<Activity> | (activity: Partial<Activity>, description?: string) => void, description?: string, _timeout?: number): TestFlow

Parameters

userSays: string | Partial<Activity>

Text or activity simulating user input.

expected: string | Partial<Activity> | (activity: Partial<Activity>, description?: string) => void

Expected text or activity of the reply sent by the bot.

description: string

(Optional) Description of the test case. If not provided one will be generated.

_timeout: number

(Optional) number of milliseconds to wait for a response from bot. Defaults to a value of 3000.

Returns

TestFlow

A new TestFlow object that appends this exchange to the modeled exchange.

Remarks

This is simply a wrapper around calls to send() and assertReply(). This is such a common pattern that a helper is provided.

adapter.test('hi', 'Hello World')
       .then(() => done());

testActivities(Partial<Activity>[], string, number)

Test a list of activities.

function testActivities(activities: Partial<Activity>[], description?: string, timeout?: number): TestFlow

Parameters

activities: Partial<Activity>[]

Array of activities.

description: string

(Optional) Description of the test case. If not provided one will be generated.

timeout: number

(Optional) number of milliseconds to wait for a response from bot. Defaults to a value of 3000.

Returns

TestFlow

A new TestFlow object that appends this exchange to the modeled exchange.

Remarks

Each activity with the "bot" role will be processed with assertReply() and every other activity will be processed as a user message with send().

throwOnExchangeRequest(string, string, string, string)

Adds an instruction to throw an exception during exchange requests.

function throwOnExchangeRequest(connectionName: string, channelId: string, userId: string, exchangeableItem: string)

Parameters

connectionName: string

The connection name.

channelId: string

The channel id.

userId: string

The user id.

exchangeableItem: string

The exchangeable token or resource URI.

Inherited Method Details

continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)

Asynchronously resumes a conversation with a user, possibly after some time has gone by.

function continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

claimsIdentity: ClaimsIdentity

A ClaimsIdentity for the conversation.

reference: Partial<ConversationReference>

A partial ConversationReference to the conversation to continue.

logic: (context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the async operation

Inherited From BotAdapter.continueConversationAsync

continueConversationAsync(ClaimsIdentity, Partial<ConversationReference>, string, (context: TurnContext) => Promise<void>)

Asynchronously resumes a conversation with a user, possibly after some time has gone by.

function continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, audience: string, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

claimsIdentity: ClaimsIdentity

A ClaimsIdentity for the conversation.

reference: Partial<ConversationReference>

A partial ConversationReference to the conversation to continue.

audience: string

A value signifying the recipient of the proactive message.

logic: (context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the async operation

Inherited From BotAdapter.continueConversationAsync

continueConversationAsync(string, Partial<ConversationReference>, (context: TurnContext) => Promise<void>)

Asynchronously resumes a conversation with a user, possibly after some time has gone by.

function continueConversationAsync(botAppId: string, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

botAppId: string

The application ID of the bot. This parameter is ignored in single tenant the Adapters (Console,Test, etc) but is critical to the BotFrameworkAdapter which is multi-tenant aware.

reference: Partial<ConversationReference>

A partial ConversationReference to the conversation to continue.

logic: (context: TurnContext) => Promise<void>

The asynchronous method to call after the adapter middleware runs.

Returns

Promise<void>

a promise representing the async operation

Inherited From BotAdapter.continueConversationAsync

createConversationAsync(string, string, string, string, ConversationParameters, (context: TurnContext) => Promise<void>)

Creates a conversation on the specified channel.

function createConversationAsync(_botAppId: string, _channelId: string, _serviceUrl: string, _audience: string, _conversationParameters: ConversationParameters, _logic: (context: TurnContext) => Promise<void>): Promise<void>

Parameters

_botAppId: string

The application ID of the bot.

_channelId: string

The ID for the channel.

_serviceUrl: string

The ID for the channel.

_audience: string

The audience for the connector.

_conversationParameters: ConversationParameters

The conversation information to use to create the conversation

_logic: (context: TurnContext) => Promise<void>

The method to call for the resulting bot turn.

Returns

Promise<void>

A promise that represents the asynchronous operation

Remarks

To start a conversation, your bot must know its account information and the user's account information on that channel. Most _channels only support initiating a direct message (non-group) conversation.

The adapter attempts to create a new conversation on the channel, and then sends a conversationUpdate activity through its middleware pipeline to the logic method.

If the conversation is established with the specified users, the ID of the activity's converstion will contain the ID of the new conversation.

Inherited From BotAdapter.createConversationAsync

use((context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[])

Adds middleware to the adapter's pipeline.

function use(middlewares: (context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[]): this

Parameters

middlewares: (context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[]

The middleware or middleware handlers to add.

Returns

this

The updated adapter object.

Remarks

Middleware is added to the adapter at initialization time. Each turn, the adapter calls its middleware in the order in which you added it.

Inherited From BotAdapter.use