@empiricalrun/playwright-utils 0.13.14 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @empiricalrun/playwright-utils
 
+## 0.14.0
+
+### Minor Changes
+
+- d4d123a: feat: auth utils for user repos to do conditional logins
+
 ## 0.13.14
 
 ### Patch Changes

package/README.md

@@ -11,64 +11,5 @@ Playwright utils for test code repos of our customers
 - Vision capabilities
   - `locator.query` API
   - Captcha
-- Email automation
-  
-## Email automation
-
-### Example usage
-
-#### Dynamic email
-
-This dynamically generates a random email address that can 
-be used for the test (e.g. invite a new user).
-
-```ts
-import { EmailClient } from "@empiricalrun/playwright-utils";
-
-const client = new EmailClient();
-const address = client.getAddress();
-
-// Input the `address` in the application
-// that sends the email.
-
-// Get email received on the `address`
-const email = await client.waitForEmail();
-```
-
-#### Static email
-
-This uses a known (static) email that can be used to login
-into an application.
-
-This needs an email id (e.g. `test-login-user`). The email id
-is appended with the domain (managed internally) to get the full
-email address.
-
-```ts
-import { EmailClient } from "@empiricalrun/playwright-utils";
-
-const emailId = `test-login-user`;
-
-const client = new EmailClient({ emailId });
-const address = client.getAddress(); // Returns full address with domain
-
-// Get email received on the `address`
-const email = await client.waitForEmail();
-
-// Get login OTP
-const loginCode = email.codes[0];
-```
-
-#### Add reporter
-
-To use the custom HTML reporter, add the following to your Playwright config:
-
-```ts
-import { defineConfig } from "@playwright/test";
-import { baseConfig } from "@empiricalrun/playwright-utils";
-
-export default defineConfig({
-  ...baseConfig,
-  ...
-});
-```
+- [Email automation](./docs/email.md)
+- [Authentication](./docs/auth.md)

package/dist/auth/index.d.ts

@@ -0,0 +1,17 @@
+import { Page } from "playwright-core";
+type WithKey<T> = T & {
+    key: string;
+};
+export declare class AuthStore<T extends WithKey<{}>> {
+    private page;
+    private userContext;
+    private loginFunc;
+    private checkLoggedInFunc;
+    constructor(page: Page, userContext: T, loginFunc: (page: Page, userContext: T) => Promise<void>, checkLoggedInFunc: (page: Page, userContext: T) => Promise<boolean>);
+    loginIfRequired(): Promise<void>;
+    static location(userContext: {
+        key: string;
+    }): string;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,qBAAa,SAAS,CAAC,CAAC,SAAS,OAAO,CAAC,EAAE,CAAC;IAExC,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,iBAAiB;gBAHjB,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,CAAC,EACd,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EACxD,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC;IAGvE,eAAe;IAoBrB,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;CAGtD"}

package/dist/auth/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthStore = void 0;
+class AuthStore {
+    page;
+    userContext;
+    loginFunc;
+    checkLoggedInFunc;
+    constructor(page, userContext, loginFunc, checkLoggedInFunc) {
+        this.page = page;
+        this.userContext = userContext;
+        this.loginFunc = loginFunc;
+        this.checkLoggedInFunc = checkLoggedInFunc;
+    }
+    async loginIfRequired() {
+        let shouldDoLogin = false;
+        try {
+            const hasLoggedIn = await this.checkLoggedInFunc(this.page, this.userContext);
+            shouldDoLogin = !hasLoggedIn;
+        }
+        catch (e) {
+            shouldDoLogin = true;
+        }
+        if (shouldDoLogin) {
+            await this.loginFunc(this.page, this.userContext);
+            const storagePath = AuthStore.location(this.userContext);
+            await this.page.context().storageState({ path: storagePath });
+        }
+    }
+    // TODO: make this async
+    static location(userContext) {
+        return `auth/${userContext.key}.json`;
+    }
+}
+exports.AuthStore = AuthStore;

package/docs/auth.md

@@ -0,0 +1,50 @@
+# Authentication utilities
+
+This builds around playwright's `storageState` primitive which is used to cache 
+auth related state (in a json file on disk).
+
+This requires an object of `UserContext` type, which has a `key: string`. The
+rest of the object can be custom.
+
+## Usage
+
+### Login if required
+
+```ts
+import { login } from "../pages/login";
+import { test as setup } from "./fixtures";
+import { AuthStore } from "@empiricalrun/playwright-utils";
+
+setup("login to application", async ({ page, userContext }) => {
+  const auth = new AuthStore(
+    page,
+    userContext,
+    // Pass login method
+    login,
+    // Pass login checker method
+    (page, userContext) => {
+      const postLoginElement = page.getByRole("button", { name: "Search" });
+      await postLoginElement.waitFor();
+      return postLoginElement.isVisible();
+    }
+  );
+
+  await auth.loginIfRequired();
+  await page.context().storageState({ path: authFile });
+});
+```
+
+### Get auth state location
+
+```ts
+// in your playwright.config.ts
+import { AuthStore } from "@empiricalrun/playwright-utils";
+
+projects: [
+  name: "chromium",
+  use: {
+    storageState: AuthStore.location(userContext)
+    // ...
+  }
+]
+```

package/docs/email.md

@@ -0,0 +1,45 @@
+## Email automation
+
+### Example usage
+
+#### Dynamic email
+
+This dynamically generates a random email address that can 
+be used for the test (e.g. invite a new user).
+
+```ts
+import { EmailClient } from "@empiricalrun/playwright-utils";
+
+const client = new EmailClient();
+const address = client.getAddress();
+
+// Input the `address` in the application
+// that sends the email.
+
+// Get email received on the `address`
+const email = await client.waitForEmail();
+```
+
+#### Static email
+
+This uses a known (static) email that can be used to login
+into an application.
+
+This needs an email id (e.g. `test-login-user`). The email id
+is appended with the domain (managed internally) to get the full
+email address.
+
+```ts
+import { EmailClient } from "@empiricalrun/playwright-utils";
+
+const emailId = `test-login-user`;
+
+const client = new EmailClient({ emailId });
+const address = client.getAddress(); // Returns full address with domain
+
+// Get email received on the `address`
+const email = await client.waitForEmail();
+
+// Get login OTP
+const loginCode = email.codes[0];
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empiricalrun/playwright-utils",
-  "version": "0.13.14",
+  "version": "0.14.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"