npm package: @microsoft/teams-js-mock
Description: A mocking library to support testing of Microsoft Hosts Client SDK
Latest version: 0.1.0-alpha.2

# Teams-JS Mocking Library

The Teams JS Mocking Library is stubs the [team-js](https://www.npmjs.com/package/@microsoft/teams-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

```bash
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`](https://sinonjs.org/) to intercept and mock out calls to the Teams Javascript Client Library/SDK.

### Returning default values for all SDK calls

```javascript
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.

```javascript
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](https://fakerjs.dev/) to generate this fake data.

If you want to fix the return values of a function you can set the seed used by Faker.

```javascript
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.

```javascript
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.

```typescript
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](https://sinonjs.org/releases/v15/stubs/) directly.

```typescript
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.

```javascript
mockedMicrosoftTeams.setScenario('meeting');
```

Multiple scenarios can be chained:

```typescript
mockedMicrosoftTeams.setScenario(Scenario.Meeting).setScenario(Scenario.Channel);
```

The current supported scenarios are

```typescript
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.](/README.md)

## 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](/packages/playwright-teams), for use in integration tests. If you have any feedback we would love to hear from you.