\n \n A performance-testing tool for your preact based app\n \n
\n\n## Overview\n\nThis utility allows you to instrument your preact application bundle, and to write performance tests using [playwright](https://playwright.dev/) to assert on the framework activity (rerenders, unmountings, etc) during an interaction.\n\nUsing this tool, you can ensure that performance doesn't regress unintentionally. \n\nKnow the story behind the tool in our [Blog Post](https://tech.loveholidays.com/from-manual-grind-to-automated-bliss-introducing-preact-perf-metrics-d37ce188532b), and check the [/example code](/example) for practical information.\n\nMade with ❤️ by loveholidays.com\n\n--- \n\n## Usage\n\nSee an example application in the [/example](example/README.md) subdirectory.\n\n#### 1- Install the library\n\n```bash\nnpm install @loveholidays/preact-perf-metrics\n```\n\n#### 2- Instrument your application\n\n```js\nimport { setup } from \"@loveholidays/preact-perf-metrics/lib/setup\"\n\n// ... somewhere in your app entry-point\nsetup();\n```\n\n> [!NOTE]\n> you might want to call `setup()` only in a testing environment (and **not** in the production build) because the instrumentation adds some overhead.\n> Similarly to what you would do with `preact/debug` for the devtools.\n\n#### 3- Configure Playwright extension\n\nThis extends the `expect` function to support the libraries' custom matchers.\n\n```js\nimport { expect } from '@playwright/test';\nimport { extension } from '@loveholidays/preact-perf-metrics';\nexpect.extend(extension);\n```\n\n> [!NOTE]\n> This can also be done on the test file itself or in another file (see [playwright-custom-matchers docs](https://playwright.dev/docs/test-assertions#add-custom-matchers-using-expectextend))\n\n#### 4- Write tests\n\nWrite performance tests using `reset()` (reset the counters) and the custom matchers (`toPerform()`, `toRerender()`)\n\n```js\nimport { expect, test } from '@playwright/test';\nimport { reset } from '@loveholidays/preact-perf-metrics';\n\ntest(\"...\", await ({page}) => {\n await page.goto('...');\n\n // prepare: clear the counters\n await reset(page); /\n\n // action\n await page.getByText('Button').click();\n\n // test: use of custom matcher `toPerform`\n await expect(page).toPerform({ nodesRendered: 1, renderPhases: 1 });\n})\n```\n\n## API\n\nThe API can be divided in two:\n* to instrument the application that runs in the browser: `setup()`, \n* to write playwright tests: `reset()`, `expect.toPerform()`, and `expect.toRerender()`\n\n\n### `setup()`\nInstruments the application to update the counters in `window.__PREACT_PERF_METRICS__` upon any preact internal activity (renders, unmounting, etc).\n\n### `reset()`\nPlaywright utility to reset all the counters (accummulators) to zero. Used to set the beginning of a measurement.\n\n### `expect().toPerform(...)`\n[Playwright Custom matcher](https://playwright.dev/docs/test-assertions#add-custom-matchers-using-expectextend) to assert on the framework activity during an interaction.\n\nThe parameter to assert is an object with one or many of the following keys:\n\n```js\ninterface Counters {\n nodesRendered?: number;\n renderPhases?: number;\n nodesUnmmouted?: number;\n}\n```\n\nExample:\n```js\nawait reset();\nawait page.locator('.counter').click();\nawait expect(page).toPerform({ nodesRendered: 1 });\n```\n\n### `expect().toRerender(...)`\n\n[Playwright Custom matcher](https://playwright.dev/docs/test-assertions#add-custom-matchers-using-expectextend) to assert on the list of nodes rendered during an interaction.\n\nThe parameter to assert is an array of strings, with the names of the preact-nodes involved:\n\nExample:\n\n```js\nawait reset();\nawait page.locator('.counter').click();\nawait expect(page).toRerender([\"MyCounterPage\", \"Button\"]);\n```\n\n\n--- \n \n## Contributing\n\nPlease see our [contributing guidelines](./CONTRIBUTING.md)\n\n--- \n\n## License\n\nMIT\n","readmeFilename":"README.md"}