feat(playwright): solidify identities, major release

Author: dnotes

.changeset/chatty-books-glow.md

@@ -1,5 +1,5 @@
 ---
-"@quickpickle/playwright": major
+"@quickpickle/playwright": minor
 ---
 
 Added multiple browser identities for playwright.

.changeset/red-dancers-switch.md

@@ -0,0 +1,40 @@
+---
+"@quickpickle/playwright": major
+---
+
+## 1.0 release
+
+From this point forward, the step definitions in "actions" and "outcomes"
+should be stable, and any changes to the step names will result in a new
+minor version release.
+
+I was hoping to have some system for using only *some* of the step definitions
+provided by the module, or for overriding or deleting them, but I think that
+will have to wait for the next major release.
+
+### Identities
+
+The last thing added for this release is the functionality for multiple browsers
+or "identities". Switching identity starts a new browser context, with completely
+new local data, making it possible to test interactions between different users.
+
+Each test will start with a "default" identity, and new browser contexts open
+on the same url as the "default" identity.
+
+Note that no actual *user* is created as a result of switching identity; if you
+need more setup, you can create a custom world constructor extending the
+PlaywrightWorld class and override the "setIdentity" method.
+
+The following new step definitions all simply call "world.setIdentity()", which
+creates a new browser context if necessary and switches to it:
+
+- `(as )a/an/the (user ){string}`
+- `(as )a/an/the {string} user/role/browser/identity`
+- `I am {string}`
+- `I am a/an/the (user ){string}`
+- `I am a/an/the {string} user/role/browser/identity`
+- `as {string}`
+
+### New step definitions
+
+`I am on the home/front page` opens the base url.

packages/playwright/src/PlaywrightWorld.ts

@@ -66,7 +66,7 @@ export class PlaywrightWorld extends VisualWorld implements VisualWorldInterface
   browser!: Browser
 
   identities: Map<string, BrowserMap> = new Map()
-  private _identity:string = 'default'
+  _identity:string = 'default'
 
   constructor(context:TestContext, info:InfoConstructor) {
     super(context, info)
@@ -79,19 +79,6 @@ export class PlaywrightWorld extends VisualWorld implements VisualWorldInterface
     await this.newIdentity('default')
     await this.setViewportSize()
   }
-
-  async newIdentity(name:string) {
-    let context = await this.browser.newContext({
-      serviceWorkers: 'block',
-      javaScriptEnabled: this.tagsMatch(this.worldConfig.nojsTags) ? false : true,
-    })
-    let page = await context.newPage()
-    this.identities.set(name, {
-      context,
-      page
-    })
-  }
-
   get browserContext() {
     return this.identities.get(this.identity)!.context
   }
@@ -103,7 +90,26 @@ export class PlaywrightWorld extends VisualWorld implements VisualWorldInterface
   }
   set identity(name:string) {
     if (this.identities.has(name)) this._identity = name
-    else throw new Error(`There is no browser for "${name}"; please call \`await world.newIdentity('${name}')\` first.`)
+    else throw new Error(`There is no browser for "${name}"; please call \`await world.setIdentity('${name}')\` instead.`)
+  }
+  async newIdentity(name:string) {
+    let context = await this.browser.newContext({
+      serviceWorkers: 'block',
+      javaScriptEnabled: this.tagsMatch(this.worldConfig.nojsTags) ? false : true,
+    })
+    let page = await context.newPage()
+    if (name !== 'default') {
+      let url = this.identities.get('default')!.page.url()
+      await page.goto(url, { timeout: this.worldConfig.stepTimeout })
+    }
+    this.identities.set(name, {
+      context,
+      page
+    })
+  }
+  async setIdentity(name:string) {
+    if (!this.identities.has(name)) await this.newIdentity(name)
+    this._identity = name
   }
 
   get browserName() {

packages/playwright/src/actions.steps.ts

@@ -5,6 +5,9 @@ import { expect } from '@playwright/test'
 // ================
 // Navigation
 
+Given('I am on the home/front page', async function (world:PlaywrightWorld) {
+  await world.page.goto(world.baseUrl.toString(), { timeout:world.worldConfig.stepTimeout })
+})
 Given('I am on {string}', async function (world:PlaywrightWorld, path) {
   let url = new URL(path, world.baseUrl)
   await world.page.goto(url.href, { timeout:world.worldConfig.stepTimeout })
@@ -30,26 +33,25 @@ When('I go back/forward/forwards', async function (world:PlaywrightWorld) {
 })
 
 // ================
-// Interaction
+// Identities
 
-Given('a/an/the {string}( user)( role)( browser)( identity)', async function (world:PlaywrightWorld, identity) {
-  await world.newIdentity(identity)
+Given('(as )a/an/the (user ){string}', async function (world:PlaywrightWorld, identity) {
+  await world.setIdentity(identity)
 })
-Given('I am (logged in as ){string}', async function (world:PlaywrightWorld, identity) {
-  if (!world.identities.has(identity)) await world.newIdentity(identity)
-  world.identity = identity
+Given('(as )a/an/the {string} user/role/browser/identity', async function (world:PlaywrightWorld, identity) {
+  await world.setIdentity(identity)
 })
-Given('I am (logged in as )a/an/the {string}( user)( role)( browser)( identity)', async function (world:PlaywrightWorld, identity) {
-  if (!world.identities.has(identity)) await world.newIdentity(identity)
-  world.identity = identity
+Given('I am {string}', async function (world:PlaywrightWorld, identity) {
+  await world.setIdentity(identity)
 })
-Then('as {string}', async function (world:PlaywrightWorld, identity) {
-  if (!world.identities.has(identity)) await world.newIdentity(identity)
-    world.identity = identity
+Given('I am a/an/the (user ){string}', async function (world:PlaywrightWorld, identity) {
+  await world.setIdentity(identity)
 })
-Then('as a/an/the {string}( user)( role)( browser)( identity)', async function (world:PlaywrightWorld, identity) {
-  if (!world.identities.has(identity)) await world.newIdentity(identity)
-    world.identity = identity
+Given('I am a/an/the {string} user/role/browser/identity', async function (world:PlaywrightWorld, identity) {
+  await world.setIdentity(identity)
+})
+Then('as {string}', async function (world:PlaywrightWorld, identity) {
+  await world.setIdentity(identity)
 })
 
 // ================

packages/playwright/tests/playwright-identities-html.feature

@@ -1,3 +1,4 @@
+@webserver
 Feature: Multiple browsers with identities
 
   As a developer
@@ -6,18 +7,17 @@ Feature: Multiple browsers with identities
 
   @soft
   Scenario: IndexedDB steps fail properly
-    Given I am on "http://example.com"
+    Given I am on the front page
     And a db record for "test" with value "does it work?"
     Then the db record for "test" should be "well does it?"
     Then error 1 should contain '"value": "does it work?"'
     And clear 1 error
 
   Scenario: IndexedDB is separate for each identity
-    Given I am "user1"
-    And I am on "http://example.com"
-    And a db record for "test" with value "user1"
-    When I am "user2"
-    And I am on "http://example.com"
-    Given a db record for "test" with value "user2"
-    When I am "user1"
+    Given I am on the front page
+    Given I am a user "user1"
+    And there is a db record for "test" with value "user1"
+    Given a user "user2"
+    And a db record for "test" with value "user2"
+    Then as "user1"
     Then the db record for "test" should be "user1"

packages/playwright/tests/playwright.steps.ts

@@ -89,7 +89,7 @@ Given('the following world config:', async (world:PlaywrightWorld, rawConf:DocSt
 })
 
 // IndexedDB
-Given('a(n) (indexed)db record for {string} with value {string}', async (world:PlaywrightWorld, key:string, value:string) => {
+Given('(there is )a(n) (indexed)db record for {string} with value {string}', async (world:PlaywrightWorld, key:string, value:string) => {
   await world.page.evaluate(async ([key, value]) => {
     return new Promise<void>((resolve, reject) => {
       const request = indexedDB.open('testing', 1);