@thisisagile/easy-puppeteer 20.1.1 → 21.0.0

package/README.md

@@ -280,3 +280,14 @@ The `@requires` decorator group also contains `@requires.labCoat()` this decorat
 
 To use these decorators, the generic `security` middleware must be loaded first. In most cases, it should be added to the `pre` list of handlers of a service.
 The security middleware takes an optional configuration object, which is documented [in code](packages/easy-express/src/express/SecurityHandler.ts).
+
+## Side effects and tree shaking
+Every package declares `sideEffects` in its `package.json`, so a bundler only keeps the modules a consumer actually uses. Contributors keep that declaration true by following these rules:
+
+- **No module-level mutation of anything outside the module.** Do not patch globals, prototypes or imported objects when a module loads. If something must be configured, configure it in the module that needs it, so it is kept exactly when that module is used.
+- **Catalogue values are pure factories.** Build enum and catalogue values with plain constructors or factory calls that only create objects, so an unused value can be dropped.
+- **A module that must run for its effect on import is listed explicitly.** `easy-test` lists its index and matcher files because `import '@thisisagile/easy-test'` exists to call `expect.extend`. `easy-test-react` lists its index because importing it mocks the timezone. Runtime packages declare `false`.
+- **`DateTime` and `Meta` are deliberately not listed.** `DateTime` extends Day.js and `Meta` loads `reflect-metadata` at module level, but only their own exports need that setup. Bundlers keep a module's top-level code whenever any of its exports are used, so they stay correct unlisted. Listing them would make every root import, such as `isDefined`, pay for Day.js and `reflect-metadata`.
+- **No `emitDecoratorMetadata`.** Nothing in easy reads `design:` metadata; decorators store what they need under their own keys.
+
+`test/bundle/workspaces.mjs` checks these rules against the packed packages.

package/dist/PuppeteerTester.d.ts

@@ -1,12 +1,7 @@
-import { Id, UseCase } from "@thisisagile/easy";
 import { Browser, Page } from "puppeteer";
-import { TestElement, Tester } from "@thisisagile/easy-test-web";
+import { ClosableBrowserTester, TestElement, Tester } from "@thisisagile/easy-test-web";
 //#region src/PuppeteerTester.d.ts
-export declare class PuppeteerTester implements Tester {
-  host: string;
-  private readonly browser;
-  private readonly page;
-  constructor(host: string, browser: Browser, page: Page);
+export declare class PuppeteerTester extends ClosableBrowserTester<Page> implements Tester {
   get url(): string;
   static launch: (headless?: boolean, launchProps?: {}) => Promise<Browser>;
   static init(host?: string, headless?: boolean, width?: number, height?: number, launchProps?: {}): Promise<Tester>;
@@ -17,10 +12,6 @@ export declare class PuppeteerTester implements Tester {
   by(key: string, value: string): TestElement;
   submit(): TestElement;
   row(contains: string): TestElement;
-  redirect(url: string): Promise<boolean>;
-  goto(to: UseCase, id?: Id): Promise<boolean>;
-  wait(): Promise<boolean>;
-  close(): Promise<void>;
   private byXPath;
 }
 //#endregion

package/dist/PuppeteerTester.js

@@ -1,17 +1,9 @@
 import { PuppeteerElement } from "./PuppeteerElement.js";
 import { ctx } from "@thisisagile/easy";
 import puppeteer from "puppeteer";
-import { toUrl } from "@thisisagile/easy-test-web";
+import { ClosableBrowserTester } from "@thisisagile/easy-test-web";
 //#region src/PuppeteerTester.ts
-var PuppeteerTester = class PuppeteerTester {
-	host;
-	browser;
-	page;
-	constructor(host, browser, page) {
-		this.host = host;
-		this.browser = browser;
-		this.page = page;
-	}
+var PuppeteerTester = class PuppeteerTester extends ClosableBrowserTester {
 	get url() {
 		return this.page.url();
 	}
@@ -55,18 +47,6 @@ var PuppeteerTester = class PuppeteerTester {
 	row(contains) {
 		return this.byXPath(`//tr[contains(., '${contains}')]`);
 	}
-	redirect(url) {
-		return this.page.goto(url).then((r) => r?.ok() ?? false);
-	}
-	goto(to, id) {
-		return this.redirect(toUrl(to, this.host, id));
-	}
-	wait() {
-		return this.page.waitForNavigation().then((r) => r?.ok() || false);
-	}
-	close() {
-		return this.browser.close();
-	}
 	byXPath(q) {
 		const h = this.page.waitForSelector(`xpath/.${q}`);
 		return new PuppeteerElement(h);

package/dist/PuppeteerTester.js.map

@@ -1 +1 @@
-{"version":3,"file":"PuppeteerTester.js","names":[],"sources":["../src/PuppeteerTester.ts"],"sourcesContent":["import { PuppeteerElement } from './PuppeteerElement';\nimport puppeteer, { Browser, ElementHandle, Page } from 'puppeteer';\nimport { ctx, Id, UseCase } from '@thisisagile/easy';\nimport { TestElement, Tester, toUrl } from '@thisisagile/easy-test-web';\n\nexport class PuppeteerTester implements Tester {\n  constructor(public host: string, private readonly browser: Browser, private readonly page: Page) {}\n\n  get url(): string {\n    return this.page.url();\n  }\n\n  /* istanbul ignore next */\n  static launch = (headless = true, launchProps = {}): Promise<Browser> =>\n    puppeteer.launch({ headless: headless ? 'shell' : false, args: ['--no-sandbox', '--start-maximized'], ...launchProps });\n\n  /* istanbul ignore next */\n  static async init(host: string = ctx.env.get('webHost', '') as string, headless = true, width = 1200, height = 800, launchProps = {}): Promise<Tester> {\n    const browser = await PuppeteerTester.launch(headless, launchProps);\n    const page = await browser.newPage();\n    await page.setViewport({ width, height });\n    return new PuppeteerTester(host, browser, page);\n  }\n\n  byClass(c: string): TestElement {\n    const h = this.page.waitForSelector(`.${c}`);\n    return new PuppeteerElement(h);\n  }\n\n  byId(id: string): TestElement {\n    const h = this.page.waitForSelector(`#${id}`);\n    return new PuppeteerElement(h);\n  }\n\n  byDataTestId(id: string): TestElement {\n    return this.by('data-testid', id);\n  }\n\n  byName(name: string): TestElement {\n    return this.by('name', name);\n  }\n\n  by(key: string, value: string): TestElement {\n    const h = this.page.waitForSelector(`[${key}=${value}]`);\n    return new PuppeteerElement(h);\n  }\n\n  submit(): TestElement {\n    return this.by('type', 'submit');\n  }\n\n  row(contains: string): TestElement {\n    // Select the first row that contains the given input. byXPath prefixes the query with a dot,\n    // so it must stay relative: '(//tr[...])[1]' would become '.(//tr[...])[1]', which is not\n    // valid xpath - it matches nothing and only times out. waitForSelector takes the first match.\n    return this.byXPath(`//tr[contains(., '${contains}')]`);\n  }\n\n  redirect(url: string): Promise<boolean> {\n    return this.page.goto(url).then(r => r?.ok() ?? false);\n  }\n\n  goto(to: UseCase, id?: Id): Promise<boolean> {\n    return this.redirect(toUrl(to, this.host, id));\n  }\n\n  wait(): Promise<boolean> {\n    return this.page.waitForNavigation().then(r => r?.ok() || false);\n  }\n\n  close(): Promise<void> {\n    return this.browser.close();\n  }\n\n  private byXPath(q: string): TestElement {\n    const h = this.page.waitForSelector(`xpath/.${q}`);\n    return new PuppeteerElement(h as Promise<ElementHandle<Element>>);\n  }\n}\n"],"mappings":";;;;;AAKA,IAAa,kBAAb,MAAa,gBAAkC;CAC1B;CAA+B;CAAmC;CAArF,YAAY,MAAqB,SAAmC,MAA6B;EAA9E,KAAA,OAAA;EAA+B,KAAA,UAAA;EAAmC,KAAA,OAAA;CAAa;CAElG,IAAI,MAAc;EAChB,OAAO,KAAK,KAAK,IAAI;CACvB;;CAGA,OAAO,UAAU,WAAW,MAAM,cAAc,CAAC,MAC/C,UAAU,OAAO;EAAE,UAAU,WAAW,UAAU;EAAO,MAAM,CAAC,gBAAgB,mBAAmB;EAAG,GAAG;CAAY,CAAC;;CAGxH,aAAa,KAAK,OAAe,IAAI,IAAI,IAAI,WAAW,EAAE,GAAa,WAAW,MAAM,QAAQ,MAAM,SAAS,KAAK,cAAc,CAAC,GAAoB;EACrJ,MAAM,UAAU,MAAM,gBAAgB,OAAO,UAAU,WAAW;EAClE,MAAM,OAAO,MAAM,QAAQ,QAAQ;EACnC,MAAM,KAAK,YAAY;GAAE;GAAO;EAAO,CAAC;EACxC,OAAO,IAAI,gBAAgB,MAAM,SAAS,IAAI;CAChD;CAEA,QAAQ,GAAwB;EAC9B,MAAM,IAAI,KAAK,KAAK,gBAAgB,IAAI,GAAG;EAC3C,OAAO,IAAI,iBAAiB,CAAC;CAC/B;CAEA,KAAK,IAAyB;EAC5B,MAAM,IAAI,KAAK,KAAK,gBAAgB,IAAI,IAAI;EAC5C,OAAO,IAAI,iBAAiB,CAAC;CAC/B;CAEA,aAAa,IAAyB;EACpC,OAAO,KAAK,GAAG,eAAe,EAAE;CAClC;CAEA,OAAO,MAA2B;EAChC,OAAO,KAAK,GAAG,QAAQ,IAAI;CAC7B;CAEA,GAAG,KAAa,OAA4B;EAC1C,MAAM,IAAI,KAAK,KAAK,gBAAgB,IAAI,IAAI,GAAG,MAAM,EAAE;EACvD,OAAO,IAAI,iBAAiB,CAAC;CAC/B;CAEA,SAAsB;EACpB,OAAO,KAAK,GAAG,QAAQ,QAAQ;CACjC;CAEA,IAAI,UAA+B;EAIjC,OAAO,KAAK,QAAQ,qBAAqB,SAAS,IAAI;CACxD;CAEA,SAAS,KAA+B;EACtC,OAAO,KAAK,KAAK,KAAK,GAAG,CAAC,CAAC,MAAK,MAAK,GAAG,GAAG,KAAK,KAAK;CACvD;CAEA,KAAK,IAAa,IAA2B;EAC3C,OAAO,KAAK,SAAS,MAAM,IAAI,KAAK,MAAM,EAAE,CAAC;CAC/C;CAEA,OAAyB;EACvB,OAAO,KAAK,KAAK,kBAAkB,CAAC,CAAC,MAAK,MAAK,GAAG,GAAG,KAAK,KAAK;CACjE;CAEA,QAAuB;EACrB,OAAO,KAAK,QAAQ,MAAM;CAC5B;CAEA,QAAgB,GAAwB;EACtC,MAAM,IAAI,KAAK,KAAK,gBAAgB,UAAU,GAAG;EACjD,OAAO,IAAI,iBAAiB,CAAoC;CAClE;AACF"}
+{"version":3,"file":"PuppeteerTester.js","names":[],"sources":["../src/PuppeteerTester.ts"],"sourcesContent":["import { PuppeteerElement } from './PuppeteerElement';\nimport puppeteer, { Browser, ElementHandle, Page } from 'puppeteer';\nimport { ctx } from '@thisisagile/easy';\nimport { ClosableBrowserTester, TestElement, Tester } from '@thisisagile/easy-test-web';\n\nexport class PuppeteerTester extends ClosableBrowserTester<Page> implements Tester {\n  get url(): string {\n    return this.page.url();\n  }\n\n  /* istanbul ignore next */\n  static launch = (headless = true, launchProps = {}): Promise<Browser> =>\n    puppeteer.launch({ headless: headless ? 'shell' : false, args: ['--no-sandbox', '--start-maximized'], ...launchProps });\n\n  /* istanbul ignore next */\n  static async init(host: string = ctx.env.get('webHost', '') as string, headless = true, width = 1200, height = 800, launchProps = {}): Promise<Tester> {\n    const browser = await PuppeteerTester.launch(headless, launchProps);\n    const page = await browser.newPage();\n    await page.setViewport({ width, height });\n    return new PuppeteerTester(host, browser, page);\n  }\n\n  byClass(c: string): TestElement {\n    const h = this.page.waitForSelector(`.${c}`);\n    return new PuppeteerElement(h);\n  }\n\n  byId(id: string): TestElement {\n    const h = this.page.waitForSelector(`#${id}`);\n    return new PuppeteerElement(h);\n  }\n\n  byDataTestId(id: string): TestElement {\n    return this.by('data-testid', id);\n  }\n\n  byName(name: string): TestElement {\n    return this.by('name', name);\n  }\n\n  by(key: string, value: string): TestElement {\n    const h = this.page.waitForSelector(`[${key}=${value}]`);\n    return new PuppeteerElement(h);\n  }\n\n  submit(): TestElement {\n    return this.by('type', 'submit');\n  }\n\n  row(contains: string): TestElement {\n    // Select the first row that contains the given input. byXPath prefixes the query with a dot,\n    // so it must stay relative: '(//tr[...])[1]' would become '.(//tr[...])[1]', which is not\n    // valid xpath - it matches nothing and only times out. waitForSelector takes the first match.\n    return this.byXPath(`//tr[contains(., '${contains}')]`);\n  }\n\n  private byXPath(q: string): TestElement {\n    const h = this.page.waitForSelector(`xpath/.${q}`);\n    return new PuppeteerElement(h as Promise<ElementHandle<Element>>);\n  }\n}\n"],"mappings":";;;;;AAKA,IAAa,kBAAb,MAAa,wBAAwB,sBAA8C;CACjF,IAAI,MAAc;EAChB,OAAO,KAAK,KAAK,IAAI;CACvB;;CAGA,OAAO,UAAU,WAAW,MAAM,cAAc,CAAC,MAC/C,UAAU,OAAO;EAAE,UAAU,WAAW,UAAU;EAAO,MAAM,CAAC,gBAAgB,mBAAmB;EAAG,GAAG;CAAY,CAAC;;CAGxH,aAAa,KAAK,OAAe,IAAI,IAAI,IAAI,WAAW,EAAE,GAAa,WAAW,MAAM,QAAQ,MAAM,SAAS,KAAK,cAAc,CAAC,GAAoB;EACrJ,MAAM,UAAU,MAAM,gBAAgB,OAAO,UAAU,WAAW;EAClE,MAAM,OAAO,MAAM,QAAQ,QAAQ;EACnC,MAAM,KAAK,YAAY;GAAE;GAAO;EAAO,CAAC;EACxC,OAAO,IAAI,gBAAgB,MAAM,SAAS,IAAI;CAChD;CAEA,QAAQ,GAAwB;EAC9B,MAAM,IAAI,KAAK,KAAK,gBAAgB,IAAI,GAAG;EAC3C,OAAO,IAAI,iBAAiB,CAAC;CAC/B;CAEA,KAAK,IAAyB;EAC5B,MAAM,IAAI,KAAK,KAAK,gBAAgB,IAAI,IAAI;EAC5C,OAAO,IAAI,iBAAiB,CAAC;CAC/B;CAEA,aAAa,IAAyB;EACpC,OAAO,KAAK,GAAG,eAAe,EAAE;CAClC;CAEA,OAAO,MAA2B;EAChC,OAAO,KAAK,GAAG,QAAQ,IAAI;CAC7B;CAEA,GAAG,KAAa,OAA4B;EAC1C,MAAM,IAAI,KAAK,KAAK,gBAAgB,IAAI,IAAI,GAAG,MAAM,EAAE;EACvD,OAAO,IAAI,iBAAiB,CAAC;CAC/B;CAEA,SAAsB;EACpB,OAAO,KAAK,GAAG,QAAQ,QAAQ;CACjC;CAEA,IAAI,UAA+B;EAIjC,OAAO,KAAK,QAAQ,qBAAqB,SAAS,IAAI;CACxD;CAEA,QAAgB,GAAwB;EACtC,MAAM,IAAI,KAAK,KAAK,gBAAgB,UAAU,GAAG;EACjD,OAAO,IAAI,iBAAiB,CAAoC;CAClE;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thisisagile/easy-puppeteer",
-  "version": "20.1.1",
+  "version": "21.0.0",
   "description": "Straightforward wrapper library for Puppeteer web testing framework",
   "author": "Sander Hoogendoorn",
   "license": "MIT",
@@ -24,7 +24,7 @@
   "scripts": {
     "lint": "yarn g:eslint . --ext .js,.jsx,.ts,.tsx --fix",
     "format": "yarn g:prettier --check --write src test *.json",
-    "build": "yarn g:tsdown && yarn g:exports",
+    "build": "yarn g:tsdown",
     "test": "yarn g:jest --coverage",
     "prepack": "yarn g:copy-readme"
   },
@@ -42,8 +42,8 @@
     "@thisisagile/easy-test": "*"
   },
   "dependencies": {
-    "@thisisagile/easy": "^20.1.1",
-    "@thisisagile/easy-test-web": "^20.1.1",
+    "@thisisagile/easy": "^21.0.0",
+    "@thisisagile/easy-test-web": "^21.0.0",
     "puppeteer": "^24.43.1"
   },
   "exports": {

package/src/PuppeteerTester.ts

@@ -1,11 +1,9 @@
 import { PuppeteerElement } from './PuppeteerElement';
 import puppeteer, { Browser, ElementHandle, Page } from 'puppeteer';
-import { ctx, Id, UseCase } from '@thisisagile/easy';
-import { TestElement, Tester, toUrl } from '@thisisagile/easy-test-web';
-
-export class PuppeteerTester implements Tester {
-  constructor(public host: string, private readonly browser: Browser, private readonly page: Page) {}
+import { ctx } from '@thisisagile/easy';
+import { ClosableBrowserTester, TestElement, Tester } from '@thisisagile/easy-test-web';
 
+export class PuppeteerTester extends ClosableBrowserTester<Page> implements Tester {
   get url(): string {
     return this.page.url();
   }
@@ -56,22 +54,6 @@ export class PuppeteerTester implements Tester {
     return this.byXPath(`//tr[contains(., '${contains}')]`);
   }
 
-  redirect(url: string): Promise<boolean> {
-    return this.page.goto(url).then(r => r?.ok() ?? false);
-  }
-
-  goto(to: UseCase, id?: Id): Promise<boolean> {
-    return this.redirect(toUrl(to, this.host, id));
-  }
-
-  wait(): Promise<boolean> {
-    return this.page.waitForNavigation().then(r => r?.ok() || false);
-  }
-
-  close(): Promise<void> {
-    return this.browser.close();
-  }
-
   private byXPath(q: string): TestElement {
     const h = this.page.waitForSelector(`xpath/.${q}`);
     return new PuppeteerElement(h as Promise<ElementHandle<Element>>);