{"_id":"@compare-ui/playwright-test-fixture","name":"@compare-ui/playwright-test-fixture","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@compare-ui/playwright-test-fixture","version":"0.1.0","description":"Playwright component-test fixture for design comparison.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/artandrey/desing-comparison.git","directory":"packages/playwright-test-fixture"},"bugs":{"url":"https://github.com/artandrey/desing-comparison/issues"},"homepage":"https://github.com/artandrey/desing-comparison#readme","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"main":"dist/index.cjs","module":"dist/index.mjs","types":"dist/index.d.ts","publishConfig":{"access":"public"},"dependencies":{"@compare-ui/core":"0.1.0","@compare-ui/runner":"0.1.0"},"peerDependencies":{"@playwright/experimental-ct-react":">=1.40.0 <2","@playwright/test":">=1.40.0 <2","react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"devDependencies":{"@playwright/experimental-ct-react":"^1.58.2","@playwright/test":"^1.58.2","@types/pngjs":"^6.0.5","pngjs":"^7.0.0","react":"^19.2.4","react-dom":"^19.2.4","rollup":"^4.50.0","rollup-plugin-delete":"^3.0.1","rollup-plugin-dts":"^6.2.3","rollup-plugin-esbuild":"^6.2.1","tslib":"^2.8.1","@compare-ui/core":"0.1.0","@compare-ui/runner":"0.1.0"},"scripts":{"build":"rollup -c rollup.config.mjs","test":"vitest run --config vitest.config.mts"},"_id":"@compare-ui/playwright-test-fixture@0.1.0","_integrity":"sha512-gEGVf0PE7LAOGlDxmvOxbE310XMa6rRMb+NnpDtxYj0cg0f0+i5ZZcfDVpseIce0fzB4akMhgQNUmKVO7QV5bg==","_resolved":"/tmp/b5cf09299f8f4aeca9c4f53cc505dbcb/compare-ui-playwright-test-fixture-0.1.0.tgz","_from":"file:compare-ui-playwright-test-fixture-0.1.0.tgz","_nodeVersion":"21.7.3","_npmVersion":"10.5.0","dist":{"integrity":"sha512-gEGVf0PE7LAOGlDxmvOxbE310XMa6rRMb+NnpDtxYj0cg0f0+i5ZZcfDVpseIce0fzB4akMhgQNUmKVO7QV5bg==","shasum":"6fd89181f614f8c344d64538dcaf7ba9ac346e96","tarball":"https://registry.npmjs.org/@compare-ui/playwright-test-fixture/-/playwright-test-fixture-0.1.0.tgz","fileCount":6,"unpackedSize":16154,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAf8GbU7hQ2WUxkHPmdeuelpxhzSC4Uwbp3Lbf2UcyaSAiB8HSic7UibmuNfO//BS2K8+EX/olnd/J/rab/HD93dNg=="}]},"_npmUser":{"name":"artandrii","email":"artandrey7777@gmail.com"},"directories":{},"maintainers":[{"name":"artandrii","email":"artandrey7777@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/playwright-test-fixture_0.1.0_1780327631533_0.9460282397147883"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-01T15:27:11.325Z","0.1.0":"2026-06-01T15:27:11.669Z","modified":"2026-06-01T15:27:11.932Z"},"maintainers":[{"name":"artandrii","email":"artandrey7777@gmail.com"}],"description":"Playwright component-test fixture for design comparison.","homepage":"https://github.com/artandrey/desing-comparison#readme","repository":{"type":"git","url":"git+https://github.com/artandrey/desing-comparison.git","directory":"packages/playwright-test-fixture"},"bugs":{"url":"https://github.com/artandrey/desing-comparison/issues"},"license":"MIT","readme":"# `@compare-ui/playwright-test-fixture`\n\nPlaywright helpers for component-level design comparison.\n\nThis package provides:\n\n- a full fixture for registering Playwright component-test comparisons\n- a smaller helper for taking a screenshot from the current Playwright page or target\n\n## Installation\n\n```bash\npnpm add @compare-ui/playwright-test-fixture\npnpm add @playwright/test @playwright/experimental-ct-react react react-dom\n```\n\nIf you author shared comparison config directly with `@compare-ui/core`, also install it explicitly:\n\n```bash\npnpm add @compare-ui/core\n```\n\nIf your app already has Playwright and React installed, add only the missing packages.\n\n## Peer dependencies\n\nThe package expects the consuming app to provide:\n\n- `@playwright/test`\n- `@playwright/experimental-ct-react`\n- `react`\n- `react-dom`\n\nSupported peer ranges:\n\n- `@playwright/test >=1.40.0 <2`\n- `@playwright/experimental-ct-react >=1.40.0 <2`\n- `react ^18.0.0 || ^19.0.0`\n- `react-dom ^18.0.0 || ^19.0.0`\n\n## Playwright package setup\n\nThis package uses the consuming app's Playwright installation.\n\nKeep these packages on the exact same version:\n\n- `@playwright/test`\n- `@playwright/experimental-ct-react`\n\nThis is a workspace package setup requirement. The package docs and workspace validation should keep these versions aligned; the fixture does not need extra runtime enforcement for this.\n\nThe workspace also runs tarball compatibility smoke tests in CI so the published package is revalidated against more than one consumer dependency shape.\n\n## What it exports\n\nMain public APIs:\n\n- `designComparison(...)`\n- `capturePageScreenshot(...)`\n\nPublished entrypoint:\n\n- `@compare-ui/playwright-test-fixture`\n\nThat entrypoint is intended to resolve from the published build output, and the workspace verifies it through a tarball smoke test.\n\n## Full fixture\n\n`designComparison(...)` is the main high-level fixture.\n\nIt registers one Playwright test per design file and handles:\n\n- viewport setup\n- component mounting\n- screenshot capture\n- comparison execution\n- report and artifact logging\n- failure reporting\n\nThe public contract of `designComparison(...)` is:\n\n- register tests\n- fail tests when comparison does not pass\n\nIt is not a result-returning API.\n\nCall `designComparison(...)` directly in a Playwright component-test spec file.\n\nExample:\n\n```tsx\nimport { designComparison } from '@compare-ui/playwright-test-fixture';\n\nimport { ExampleScreen } from '../../src/example-screen';\n\nimport comparisonConfig from '../../design-comparison.config.mts';\n\ndesignComparison({\n  config: comparisonConfig,\n  name: 'example-screen',\n  renderComponent: () => <ExampleScreen />,\n  designFiles: [\n    {\n      viewport: { x: 320, y: 640 },\n      path: './tests/fixtures/example-screen-reference-padded.png',\n      crop: {\n        bottom: 20,\n      },\n    },\n  ],\n});\n```\n\n## Design files\n\nEach design file entry describes one comparison case.\n\n```ts\ntype ViewportSize = {\n  x: number;\n  y: number;\n};\n\ntype DesignComparisonDesignFile = {\n  viewport: ViewportSize;\n  path?: string;\n  url?: string;\n  crop?: {\n    top?: number;\n    right?: number;\n    bottom?: number;\n    left?: number;\n  };\n};\n```\n\n`viewport` represents the original design viewport. If the reference is cropped, the effective comparison viewport is derived from the cropped reference size.\n\nComparison behavior such as:\n\n- crop handling\n- explicit size normalization\n- explicit transparent-background flattening\n\ncomes from the shared `@compare-ui/core` and `@compare-ui/runner` flow, not from fixture-specific image rules in this package.\n\n## Screenshot helper\n\n`capturePageScreenshot(...)` is the smaller helper for writing a screenshot to disk from the current Playwright page or a selected screenshot target.\n\nExample shape:\n\n```ts\ntype CapturePageScreenshotOptions = {\n  page: {\n    setViewportSize(viewport: { width: number; height: number }): Promise<void>;\n  };\n  target: {\n    screenshot(args: { path: string }): Promise<void>;\n  };\n  viewport: ViewportSize;\n  screenshotPath: string;\n};\n```\n\nExample:\n\n```ts\nawait capturePageScreenshot({\n  page,\n  target: mountedComponent,\n  viewport: { x: 320, y: 620 },\n  screenshotPath: testInfo.outputPath('actual.png'),\n});\n```\n\nTypical use cases:\n\n- capture a mounted component\n- capture the current page\n- capture a selected Playwright locator-like target\n\nFor the comparison step after a screenshot already exists, use `@compare-ui/runner`.\n\n## Typical workflow\n\nAt the package level, the common workflows are:\n\n1. Use `designComparison(...)` when you want the full Playwright component-test flow.\n2. Use `capturePageScreenshot(...)` when you only need screenshot capture.\n3. Use `@compare-ui/runner` when you already have a screenshot and want to run the comparison step explicitly.\n\nWhen a comparison needs size normalization or transparent-background alignment, configure that through the shared core/runner comparison flow rather than through fixture-specific screenshot behavior.\n\n## Recipe: Component Test Against A Local Reference PNG\n\nUse this package when you already know how to mount the component in Playwright component tests and want the fixture to handle the comparison flow.\n\n```tsx\nimport { designComparison } from '@compare-ui/playwright-test-fixture';\n\nimport comparisonConfig from '../../design-comparison.config.mts';\nimport { ExampleScreen } from '../../src/example-screen';\n\ndesignComparison({\n  config: comparisonConfig,\n  name: 'example-screen',\n  renderComponent: () => <ExampleScreen />,\n  designFiles: [\n    {\n      viewport: { x: 320, y: 640 },\n      path: './tests/fixtures/example-screen-reference.png',\n      crop: {\n        bottom: 20,\n      },\n    },\n  ],\n});\n```\n\nThis recipe gives you:\n\n- one registered Playwright component test\n- automatic screenshot capture\n- comparison execution through the shared runner/core flow\n- report and artifact output when the comparison fails\n\n## Notes\n\n- This package is intended for Playwright-based usage.\n- It supports React 18 and React 19 component-test consumers within the documented peer range.\n- It is designed to be used with shared config from `design-comparison.config.mts`.\n- The workspace includes a dedicated example consumer at `apps/playwright-example`.\n","readmeFilename":"README.md","_rev":"1-d3cc7d252bd5aa57587b5a93549c7088"}