https://github.com/dfinity/internet-identity-playwright
A Playwright library to simplify the integration of Internet Identity authentication in E2E tests.
https://github.com/dfinity/internet-identity-playwright
e2e icp internet-computer playwright testing
Last synced: about 1 month ago
JSON representation
A Playwright library to simplify the integration of Internet Identity authentication in E2E tests.
- Host: GitHub
- URL: https://github.com/dfinity/internet-identity-playwright
- Owner: dfinity
- License: apache-2.0
- Created: 2024-06-10T14:43:47.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-31T07:35:27.000Z (about 2 months ago)
- Last Synced: 2026-01-31T07:36:46.568Z (about 2 months ago)
- Topics: e2e, icp, internet-computer, playwright, testing
- Language: TypeScript
- Homepage:
- Size: 768 KB
- Stars: 11
- Watchers: 5
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 🔐 Internet Identity Playwright
A [Playwright](https://playwright.dev/) library to simplify the integration of [Internet Identity](https://identity.internetcomputer.org) authentication in E2E tests.
[](https://internetcomputer.org)
[](https://github.com/dfinity/internet-identity-playwright/actions/workflows/checks.yml)
[](https://github.com/dfinity/internet-identity-playwright/actions/workflows/tests.yml)
## 🚀 Introduction
This repository offers Playwright fixtures designed to assist developers in creating end-to-end (E2E) tests for dApps utilizing Internet Identity. These pre-built scenarios allow developers to seamlessly integrate authentication flows, including the creation and reuse of identities, without needing to implement the flows themselves.
## 🖥️ Installation
```bash
# with npm
npm install --save-dev @dfinity/internet-identity-playwright
# with pnpm
pnpm add --save-dev @dfinity/internet-identity-playwright
# with yarn
yarn add -D @dfinity/internet-identity-playwright
```
## ✍️ Usage
To use the Internet Identity Playwright fixtures, follow these steps:
### 1. Import the Fixtures
In your Playwright test file, import the fixtures provided by this library.
```javascript
import {testWithII} from '@dfinity/internet-identity-playwright';
```
### 2. Write Your Tests
Use the extended fixtures in your tests to perform authentication flows.
> [!NOTE]
> The `signIn()` method automatically detects whether this is a first-time passkey flow or an existing passkey flow, handling the complexity for you.
> It is also worth noting that it always tries to reuse the same default identity that was created within a Playwright session to ensure the provided identity is reproducible.
```javascript
testWithII('should sign-in with a user', async ({page, iiPage}) => {
await page.goto('/');
await iiPage.signIn();
});
```
The `iiPage` object represents the page of your application that contains the call to action to start the authentication flow with Internet Identity.
By default, the fixture will search for a button identified by the attribute `[data-tid=login-button]`. You can customize this behavior by providing your own selector.
```javascript
const loginSelector = '#login';
testWithII('should sign-in with a user', async ({page, iiPage}) => {
await page.goto('/');
await iiPage.signIn({passkey: {selector: loginSelector}});
});
```
When creating a new passkey for the first time, the identity name is set by default to "Test". You can customize this behavior or create other accounts with the parameter `account`.
> [!NOTE]
> Creating an account requires having signed in a first time within a Playwright session.
```javascript
const loginSelector = '#login';
testWithII('should sign-in with a user', async ({page, iiPage}) => {
await page.goto('/');
await iiPage.signIn();
await page.locator('#logout').click();
await iiPage.signIn({passkey: {account: 'Hello World'}});
});
```
### 3. Wait for Internet Identity (optional)
You might encounter scenarios where you perform tests against a local replica started in parallel with your tests, commonly when automating the tests in a CI environment. The library also exposes a fixture that lets you wait for Internet Identity to be ready.
For example, you can provide the local replica URL and the canister ID on which Internet Identity has been deployed:
```javascript
testWithII.beforeEach(async ({iiPage, browser}) => {
const url = 'http://127.0.0.1:4943';
const canisterId = 'rdmx6-jaaaa-aaaaa-aaadq-cai';
await iiPage.waitReady({url, canisterId});
});
```
The function also accepts an optional timeout parameter to specify how long the function should wait for Internet Identity to be mounted, with a default value of 60000 milliseconds.
```javascript
testWithII.beforeEach(async ({iiPage, browser}) => {
const url = 'http://127.0.0.1:4943';
const canisterId = 'rdmx6-jaaaa-aaaaa-aaadq-cai';
const timeout = 30000;
await iiPage.waitReady({url, canisterId, timeout});
});
```
### 4. Run Your Tests
Run your Playwright tests as usual.
```bash
npx playwright test
```
## 💁♂️️ Tips & tricks
### Example Test
You can find an example test in the following file: [login.spec.ts](./e2e/login.spec.ts).
### Running Tests Locally
To run these tests locally, follow the steps below:
1. Install a container runtime:
Make sure you have an up-to-date container runtime installed on your machine, such as [Docker](https://www.docker.com/) or [Podman](https://podman.io/).
The suite uses Docker by default. If you're using Podman instead, update the emulator config in [demo/juno.config.mjs](./demo/juno.config.mjs):
```
emulator: {
runner: {
type: "podman"
},
satellite: {}
}
```
2. Install Juno's CLI:
```
npm i -g @junobuild/cli
```
3. Start the emulator:
Navigate to the [demo](./demo) directory and start the environment:
```bash
cd demo
juno emulator start
```
4. Setup the environment:
If this is the first time you're running the tests locally, you need to configure the backend of the demo application by authorizing your CLI to operate the demo's Satellite (canister) and applying its backend configuration:
```bash
juno login --emulator --mode development
juno config apply --mode development
```
5. Run the Tests:
Return to the root directory and execute the tests:
```bash
npm run e2e
```
### Running Captcha Tests Locally
The default test suite validates the use of Internet Identity without captcha requirements. To test a flow with captcha, run the following command in the `demo` directory:
```bash
docker compose -f docker-compose.captcha.yml up
```
Then, navigate to the root directory and run the dedicated test:
```bash
npm run e2e:captcha
```
### Running Required Passkey Tests Locally
The default test suite validates the use of the latest Internet Identity, which does not require the user to complete a specific step to create a passkey. To test a flow where passkey creation is required, run the following command from the `demo` directory:
```bash
docker compose -f docker-compose.passkey.yml up
```
Then, navigate to the root directory and run the dedicated test:
```bash
npm run e2e:passkey
```
## 🚧 Limitations
Currently, the library's fixtures cannot be implemented with Playwright's ability to [load existing authenticated state](https://playwright.dev/docs/auth). Playwright currently does not support IndexedDB for such features. This limitation is tracked in their [GitHub issue #11164](https://github.com/microsoft/playwright/issues/11164).
While it is technically possible to use local storage instead of IndexedDB, this approach is generally discouraged as it does not reflect how identities are stored in the browser. We prefer to adhere to best practices for testing to ensure the most accurate simulation of real-world scenarios.
## 🧑🤝🧑 Community
- [Forum](https://forum.dfinity.org/)
- [Discord](https://discord.internetcomputer.org)