@microsoft/teams-js-mock

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.

🚧 This project is a work in a project and is not yet released. 🚧

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 initially
• mockedMicrosoftTeams.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);
});

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