msal-react-tester. A tester package when using msal-react in your application

About

The MSAL React Tester is a NPM package to allows you creating unit tests for any of your components that need to be authenticated (or not) using the msal-react package and Azure AD.

The MSAL React Tester package is able to run by default with different javascript test runners like:

• vitest if you are creating a React application using vite.
• jest if you are creating a React application using Create React Application.

The MSAL React Tester package allows you to test your components in any of these scenario:

• Testing a react component when a user "is not" authenticated.
• Testing a react component when a user "is" authenticated.
• Testing a react component when a user "tries" to log in.
• Testing a react component when a user "tries" to log out.
• Testing a react component when a user authentication request has "failed".

Prerequisites

• You are building a react application using Create React Application or vite.
• You are using @azure/msal-react to authenticate your users on Azure AD.
• You are using the built in @testing-library/react package to create and run your tests (you are basically using the built in "test": "react-scripts test" script to execute your tests).
• You want to create unit tests without having to depends on a connection to Azure AD.
• You want to run your tests in your CI/CD.

Installation

The MSAL React Tester package is available on NPM.

1npm install --save-dev msal-react-tester

vitest

If you are using the vitest test runner, you need to add this to your config

1import { MsalReactTesterPlugin } from 'msal-react-tester'
2import { vi, expect } from 'vitest'
3
4MsalReactTesterPlugin.init({
5 spyOn: vi.spyOn,
6 expect: expect,
7 resetAllMocks: vi.resetAllMocks
8})

If you are using jest this step is not necessary.

Usage

Creates a [component].test.tsx and import the msal-react-tester package:

1import { MsalReactTester } from 'msal-react-tester';

Initialization:

• Create a new instance of MsalReactTester before each test.
  • Depending on your setup, you can create your instance to mock a Redirect authentication or a Popup authentication.
• Call the spyMsal() method to mock all the MSAL React required methods & events.
• Don not forget to call resetSpyMsal after each test.

1let msalTester: MsalReactTester;
2
3beforeEach(() => {
4  // new instance of msal tester for each test:
5  msalTester = new MsalReactTester(); 
6  // or new MsalReactTester("Redirect") / new MsalReactTester("Popup")
7
8  // Ask msal-react-tester to handle and mock all msal-react processes:
9  msalTester.spyMsal();
10});
11
12afterEach(() => {
13  // reset msal-react-tester
14  msalTester.resetSpyMsal();
15});

Testing a component without any interaction with the authentication process:

In each of your test, you can now:

• Mock an unauthenticated user, calling await msalTester.isNotLogged().
• Mock an authenticated user, calling await msalTester.isLogged().
• Creates a <MsalProvider /> using the msalTester.client as the IPublicClientApplication instance.
• Call msalTester.waitForRedirect() to let MSAL React Tester handling MSAL React processes
• Then makes any tests or assertions.

Here is an example where we are testing a <HomePage /> component during a first visit by an authenticated user:

1test('Home page render correctly when user is not logged', async () => {
2
3  // Mock a guest user, not yet authenticated:
4  await msalTester.isNotLogged();
5
6  // Render the <HomePage /> component using a <MsalProvider /> 
7  // with the mock IPublicClientApplication instance:
8  render(
9    <MsalProvider instance={msalTester.client}>
10      <MemoryRouter>
11        <Layout>
12          <HomePage />
13        </Layout>
14      </MemoryRouter>
15    </MsalProvider>,
16  );
17  
18  // Wait for msal-react-tester to handle events from msal-react:
19  await msalTester.waitForRedirect();
20
21  // Test your <HomePage /> component:
22  expect(screen.getByText(/Please sign-in/)).toBeInTheDocument();
23});
24

On the other side, you can test the same component assuming your user is "already logged", using await msalTester.isLogged().

Testing a component during an authentication process:

If you want to test a component during the authentication process, you can use await msalTester.waitForLogin():

1test('Home page render correctly when user logs in', async () => {
2
3  // Mock a guest user, not yet authenticated:
4  await msalTester.isNotLogged();
5
6  // Render the <HomePage /> component using a <MsalProvider /> 
7  // with the mock IPublicClientApplication instance:
8  render(
9    <MsalProvider instance={msalTester.client}>
10      <MemoryRouter>
11        <Layout>
12          <HomePage />
13        </Layout>
14      </MemoryRouter>
15    </MsalProvider>,
16  );
17
18  // Wait for msal-react-tester to handle events from msal-react:
19  await msalTester.waitForRedirect();
20
21  // Getting the log in button.
22  // Mock a user click to launch the log in process:
23  const signin = screen.getByRole('button', { name: 'Sign In' });
24  userEvent.click(signin);
25
26  // Wait for msal-react-tester to handle the login process from msal-react:
27  await msalTester.waitForLogin();
28
29  // From here, your user is supposed to be logged in the component:
30  expect(screen.getByRole('button', 
31    { name: msalTester.activeAccount.name })).toBeInTheDocument();
32});

On the other side, if you want to test component during a log out process, use msalTester.waitForLogout()

Example

You will find a full example in the ../example folder.

Take a look on the pages tests:

root
├── example
├──── src
├────── pages
├──────── HomePage.test.tsx
├──────── SearchPage.test.tsx

License

Licensed under the MIT License.

Contact

Feel free to contact me through twitter : @sebpertus