From fd1df7a0c2f0e9b2e1a2e87a9762e0c9f16aa434 Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:42:48 +0100 Subject: [PATCH 1/8] fix: improve readme --- README.md | 125 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 93 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index b333147..5ff6a22 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,50 @@ ![CI](https://github.com/nearform/hub-template/actions/workflows/ci.yml/badge.svg?event=push) -# Playwright-Firebase plugin +# @nearform/playwright-firebase Tidy way to authenticate Playwright E2E tests on Firebase. -## Installation +Install using npm: -In order to install this package into your playwright project use `npm install @nearform/playwright-firebase` or `yarn add @nearform-firebase` +```bash +npm install @nearform/playwright-firebase +``` + +or yarn: + +```bash +yarn add @nearform/playwright-firebase +``` + +Want to see it in action? Go to [Example](#example) to try it out! + +## Contents -## Commands +0. [Setup](#setup) +1. [Motivation](#motivation) +2. [Example](#example) -- `auth.login(page)` : logs in -- `auth.logout(page)`: logs out + ## Setup -### TypeScript +### Firebase environment variables -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 +To set up this plugin you will need three environment variables in order to authenticate with Firebase. These are: -``` -import {Credentials} from '@nearform/playwright-firebase' -export default defineConfig({ - ... - }) -``` +1. [Firebase Service Account](https://firebase.google.com/docs/app-distribution/authenticate-service-account) +2. [Firebase User ID](https://firebase.google.com/docs/auth/web/manage-users) +3. [Firebase Configurations](https://support.google.com/firebase/answer/7015592?hl=en#zippy=%2Cin-this-article) -Create a setup file that is ran before all tests, where we'll redefine test, so you can import it from your setup file with the `auth` fixture added. +For more information about Firebase you can read the documentation [here](https://firebase.google.com/docs/auth/web/start) -``` +It's recommended to place these values in a `.env` file. Make sure to **NOT COMMIT THIS FILE**. For clarity, the Firebase User ID is often abbreviated to UID, as you will find below. + +### 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](https://playwright.dev/docs/test-fixtures). 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` + +```ts // auth.setup.ts import playwrightFirebasePlugin from '@nearform/playwright-firebase' import { test as base } from '@playwright/test' @@ -39,26 +55,71 @@ const options = JSON.parse(process.env.REACT_APP_FIREBASE_CONFIG!) export const test = playwrightFirebasePlugin(serviceAccount, options, uid, base) ``` -The default Firebase version used is `10.5.0`. In order to change this you can pass the version into the `playwrightFirebasePlugin` function as an optional fifth argument: +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`. -``` -playwrightFirebasePlugin(serviceAccount, options, uid, base, version) -``` +```ts +//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' -Where your secrets are stored in a `.env` file. Make sure to **NOT COMMIT THIS FILE**. -Now, by using the new `test` we can incorporate the `auth` generated from the package. +// 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. -``` -import { expect } from '@playwright/test'; -import { test } from '../auth.setup' -import { Page } from '@playwright/test'; -test('has title', async ({ page, auth }: { page: Page, auth: any }) => { - await page.goto('/', { waitUntil: 'networkidle' }); - await auth.login(page) - - const txt = page.getByText('Welcome! You are now logged in') + 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 + +```ts +import { Credentials } from '@nearform/playwright-firebase' + +export default defineConfig({ + ... +}) +``` + + + +## 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. Run the following: + a. `cd ./example` + b. `npm i` + c. `npm init playwright@latest` + d. `npm run start` + +At this point, you should see a web server running on `localhost:3000`. If not, or any of the above steps did not execute, please raise an issue! + +3. 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 +4. Run `npx playwright test` From 21a501baa3c451f0f4a7c3cc446c92dc70ba5327 Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:49:27 +0100 Subject: [PATCH 2/8] fix: format --- README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5ff6a22..f2bfa1a 100644 --- a/README.md +++ b/README.md @@ -113,13 +113,12 @@ This plugin was developed with the 2nd method in mind as it is 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. Run the following: - a. `cd ./example` - b. `npm i` - c. `npm init playwright@latest` - d. `npm run start` +2. `cd ./example` +3. `npm i` +4. `npm init playwright@latest` +5. `npm run start` At this point, you should see a web server running on `localhost:3000`. If not, or any of the above steps did not execute, please raise an issue! -3. 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 -4. Run `npx playwright test` +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` From 48783998f52a82e6d872b95d81afd0688273cc54 Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:52:08 +0100 Subject: [PATCH 3/8] fix: add in status badge --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f2bfa1a..f73189c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![CI](https://github.com/nearform/hub-template/actions/workflows/ci.yml/badge.svg?event=push) +[![Continuous Integration](https://github.com/nearform/playwright-firebase/actions/workflows/ci.yml/badge.svg)](https://github.com/nearform/playwright-firebase/actions/workflows/ci.yml) # @nearform/playwright-firebase From 421a5da538e778dc851cb906fba7b33108169ec3 Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 17:00:45 +0100 Subject: [PATCH 4/8] fix: content number --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f73189c..f637bbd 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ Want to see it in action? Go to [Example](#example) to try it out! ## Contents -0. [Setup](#setup) -1. [Motivation](#motivation) -2. [Example](#example) +1. [Setup](#setup) +2. [Motivation](#motivation) +3. [Example](#example) From e2d1a198f3d6cef46d664beb682e8e96d0c6ef1a Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 17:04:54 +0100 Subject: [PATCH 5/8] fix: remove emphasis on not committing --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f637bbd..410d5aa 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Want to see it in action? Go to [Example](#example) to try it out! ### Firebase environment variables -To set up this plugin you will need three environment variables in order to authenticate with Firebase. These are: +To set up this plugin you will need three sensitive environment variables in order to authenticate with Firebase. These are: 1. [Firebase Service Account](https://firebase.google.com/docs/app-distribution/authenticate-service-account) 2. [Firebase User ID](https://firebase.google.com/docs/auth/web/manage-users) @@ -38,7 +38,7 @@ To set up this plugin you will need three environment variables in order to auth For more information about Firebase you can read the documentation [here](https://firebase.google.com/docs/auth/web/start) -It's recommended to place these values in a `.env` file. Make sure to **NOT COMMIT THIS FILE**. For clarity, the Firebase User ID is often abbreviated to UID, as you will find below. +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. ### Attaching playright-firebase as a fixture to Playwright From e21e86d2f607ba76949011ea6acc13f5665538d9 Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 17:06:02 +0100 Subject: [PATCH 6/8] fix: remove lower case Playwright --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 410d5aa..c7220e6 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ It's recommended to place these values in a `.env` file. For clarity, the Fireba ### 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](https://playwright.dev/docs/test-fixtures). 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` +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](https://playwright.dev/docs/test-fixtures). 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` ```ts // auth.setup.ts From 0ef28ac41c467b1bdb399c5aaa5e9881f6cbb643 Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 17:06:42 +0100 Subject: [PATCH 7/8] fix: remove init of playwright --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index c7220e6..91572ea 100644 --- a/README.md +++ b/README.md @@ -115,8 +115,7 @@ Within this repo we have an `example/` folder that contains a sample React appli 1. Clone this repository 2. `cd ./example` 3. `npm i` -4. `npm init playwright@latest` -5. `npm run start` +4. `npm run start` At this point, you should see a web server running on `localhost:3000`. If not, or any of the above steps did not execute, please raise an issue! From 3f9792f6506defdcd410081aa73094a2e2f1dee6 Mon Sep 17 00:00:00 2001 From: Adam Laker Illoul <85499621+Ademsk1@users.noreply.github.com> Date: Thu, 19 Oct 2023 17:20:07 +0100 Subject: [PATCH 8/8] fix: extra install + more details on env --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 91572ea..3b7f9e7 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,13 @@ To set up this plugin you will need three sensitive environment variables in ord For more information about Firebase you can read the documentation [here](https://firebase.google.com/docs/auth/web/start) -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. +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 @@ -113,11 +119,12 @@ This plugin was developed with the 2nd method in mind as it is 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. `cd ./example` -3. `npm i` -4. `npm run start` +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 not, or any of the above steps did not execute, please raise an issue! +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`