@microsoft/teams-js-mock
v0.1.0-alpha.2
Published
A mocking library to support testing of Microsoft Hosts Client SDK
Downloads
8
Readme
Teams-JS Mocking Library
The Teams JS Mocking Library is stubs the team-js SDK, allowing for easy unit testing of hosted experience apps built for Teams.
The library offers a simple API to mocks all the SDK's functions, returning accurate and logical responses.
:construction: This project is a work in a project and is not yet released. :construction:
We would love to hear your feedback.
Installation
npm install --save-dev @microsoft/teams-js-mock
Usage
@microsoft/teams-js-mock
is designed to be a simple drop in stub for teams-js
. It uses sinon.js
to intercept and mock out calls to the Teams Javascript Client Library/SDK.
Returning default values for all SDK calls
import * as microsoftTeams from '@microsoft/teams-js';
import { mockMicrosoftTeams } from '@microsoft/teams-js-mock';
const mockedMicrosoftTeams = mockMicrosoftTeams(microsoftTeams);
Passing the microsoftTeams
instance from @microsoft/teams-js
is required so that the library can stub the instance of the SDK that your app is using.
Before or after each test you should reset the SDK, this ensures that your asserts are only counting the current test's run.
afterEach(() => {
mockedMicrosoftTeams.reset();
});
Pseudorandom return values
Successful values are returned by default by this library, but where the return type of a function allows (e.g. app.getContext
) a pseudorandom response will be returned.
This is done to ensure that developers do not develop against the default responses of the library.
We are using Faker to generate this fake data.
If you want to fix the return values of a function you can set the seed used by Faker.
beforeEach(() => {
mockedMicrosoftTeams.setSeed(42);
});
Overriding the returned value
What is returned from an SDK function call can be configured.
There are two ways to configure the result of an SDK call. Using, a map of overrideDelegates, or using Sinon directly.
Override Delegates map
The Override Delegates map, is a map in the structure of the teams-js
SDK. If you set a value for an function that will be used instead of the default behaviour.
For example, if you want to reject all calls to calendar.openCalendarItem()
function, the following override map will do that.
var overrideDelegates = {
calendar: { openCalendarItem: () => Promise.reject() },
};
You can use this map in two places:
mockMicrosoftTeams(microsoftTeams, overrideDelegates);
, when you are setting up the mocks initiallymockedMicrosoftTeams.reset(overrideDelegates);
, which can be used before or after a test.
test('returns rejected promise, when overridden using reset', async () => {
mockedMicrosoftTeams.reset({
calendar: { openCalendarItem: () => Promise.reject(new Error()) },
});
await expect(
microsoftTeams.calendar.openCalendarItem({
itemId: 'mock-item-id',
}),
).rejects.toStrictEqual(new Error());
sinon.assert.calledOnce(mockedMicrosoftTeams.calendar.openCalendarItem);
});
Sinon.js
The object returned from the mockMicrosoftTeams
is an object following the structure of the teams-js SDK with a Sinon Stub for each function. This means that you can use Sinon.js functions directly.
test('returns rejected promise, when overridden using sinon', async () => {
mockedMicrosoftTeams.calendar.openCalendarItem.rejects(new Error());
await expect(
microsoftTeams.calendar.openCalendarItem({
itemId: 'mock-item-id',
}),
).rejects.toStrictEqual(new Error());
sinon.assert.calledOnce(mockedMicrosoftTeams.calendar.openCalendarItem);
});
:construction: Scenarios
This feature is under development and may change before release
We support a very limited number of scenarios that when set will change the response of certain function calls.
This allows you to set a scenario like Meeting
or Channel
and the getContext
call will contain details like the meeting or channel details.
mockedMicrosoftTeams.setScenario('meeting');
Multiple scenarios can be chained:
mockedMicrosoftTeams.setScenario(Scenario.Meeting).setScenario(Scenario.Channel);
The current supported scenarios are
export enum Scenario {
// Personal tab
Personal = 'personal',
// Channel tab
Channel = 'channel',
// Group chat tab
Group = 'group',
// Meeting tab, if Channel or Group is also specified, the meeting will be in that scenario
Meeting = 'meeting',
}
Building this library
This repository uses NPM workspaces to manage the different projects.
Details on how to build the project can be found in the root of this repository.
What this project doesn't do
This library is focused solely on unit testing, and testing scenarios that are isolated from the Teams client.
We are working on a library to support using Teams with Playwright, for use in integration tests. If you have any feedback we would love to hear from you.