@nearform/playwright-firebase

[!NOTE]
This is an ESM only package, please make sure your usage follows the rules of ESM User the following guide to learn more

Tidy way to authenticate Playwright E2E tests on Firebase.

Install using npm:

npm install @nearform/playwright-firebase

or yarn:

yarn add @nearform/playwright-firebase

Want to see it in action? Go to Example to try it out!

Contents

1. Setup
2. Motivation
3. Example

Setup

Firebase environment variables

To set up this plugin you will need three sensitive environment variables in order to authenticate with Firebase. These are:

1. Firebase Service Account
2. Firebase User ID
3. Firebase Configurations

For more information about Firebase you can read the documentation here

It's recommended to place these values in a .env file. For clarity, the Firebase User ID is often abbreviated to UID, as you will find below. The plugin accepts

• Service Account: JSON
• UID: string
• Firebase Configurations: JSON

you don't need to place quotes around these environment variables.

Attaching playright-firebase as a fixture to Playwright

Playwright is based on fixtures. You have likely already used them within Playwright, they are the { page } object that is passed in to test. More information on them here. In the very same way, we are able to add our own fixture, which we call auth to the tests. To do so, we need to create a setup file that will automatically run before all other tests. We will call this auth.setup.ts

// auth.setup.ts
import playwrightFirebasePlugin from '@nearform/playwright-firebase'
import { test as base } from '@playwright/test'

const serviceAccount = JSON.parse(process.env.SERVICE_ACCOUNT!)
const uid = process.env.REACT_APP_UID!
const options = JSON.parse(process.env.REACT_APP_FIREBASE_CONFIG!)
export const test = playwrightFirebasePlugin(serviceAccount, options, uid, base)

Above we import the test directly from @playwright/test as base and then export a new test object which is identical to base with the addition of a fixture called auth. An important note is that we should now import test from this file instead of @playwright/test.

//example.spec.ts
import { expect } from '@playwright/test'
import { test } from '../auth.setup' // <----- here we import test from our auth.setup.ts.
import { Page } from '@playwright/test'

// We now access auth in exactly the same method as we do page.
test('has title', async ({ page, auth }: { page: Page; auth: any }) => {
  await page.goto('/', { waitUntil: 'networkidle' })
  await auth.login(page) // <-- we need to pass in the page object here.

  const txt = await page.getByText('Welcome! You are now logged in')
  await expect(txt).toBeVisible()

  await auth.logout(page)

  await expect(txt).not.toBeVisible()
})

It's recommended to use await for your expect assertions after logging in/out, as the Firebase authentication is likely tied to states that require re-rendering of your application.

TypeScript

If you're using Typescript, one small addition you'll need to make is to add the type Credentials to your playwright.config.ts such that

import { Credentials } from '@nearform/playwright-firebase'

export default defineConfig<Credentials>({
  ...
})

Motivation

This package is built as a plugin for Playwright testing for the use-case of Firebase authentication. There are two methods of automating a login procedure in Playwright tests:

1. As a normal user would: inserting a real username and password into the intended fields.
2. Authenticating via the Firebase SDK directly

This plugin was developed with the 2nd method in mind as it is

• Provider agnostic: Does not need to know the specifics of the authentication provider
• A faster way of logging in, so you can focus on testing
• Better security than using a username and password.

Example

Within this repo we have an example/ folder that contains a sample React application for authenticating with the Google Provider. You'll need to setup the Firebase environment variables as described above in the setup section, but the rest is taken care of.

1. Clone this repository
2. npm i
3. cd ./example
4. npm i
5. npm run start

At this point, you should see a web server running on localhost:3000. If your screen is blank, check the console on your browser for any error messages. It's likely that you haven't place the .env file in the right location, or that you haven't filled it in correctly.

6. Make a .env file within ./example, copy and paste over the variable names from .env.sample and populate them with your real Firebase environment variables
7. Run npx playwright test