creevey 0.10.0-beta.43 → 0.10.0-beta.45

package/docs/migration-0.9-to-0.10.md

@@ -0,0 +1,144 @@
+# Migrating from Creevey 0.9 to 0.10
+
+This guide outlines the key changes and steps required to update your Creevey setup from version 0.9 to 0.10. Version 0.10 introduces several significant updates, including Playwright support, a new test context API, and changes to configuration.
+
+---
+
+## Breaking Changes
+
+### 1. Browser Configuration in `creevey.config.ts`
+
+The way browsers are configured has been updated to better distinguish between Selenium and Playwright settings.
+
+- The new `webdriver` field lets you choose your WebDriver implementation. While it defaults to Selenium for now, this may change. We recommend explicitly setting it by importing and using either `SeleniumWebdriver` or `PlaywrightWebdriver`.
+- Selenium-specific capabilities (e.g., `browserVersion`, `platformName`) must now be nested under a `seleniumCapabilities` object.
+- Playwright-specific options should be placed under a `playwrightOptions` object.
+
+**Before (0.9):**
+
+```javascript
+// creevey.config.js
+export default {
+  browsers: {
+    chrome: {
+      browserName: 'chrome',
+      browserVersion: '90.0',
+      platformName: 'linux',
+    },
+  },
+};
+```
+
+**After (0.10):**
+
+```typescript
+// creevey.config.ts
+import type { CreeveyConfig } from 'creevey';
+import { SeleniumWebdriver } from 'creevey/selenium';
+// or
+// import { PlaywrightWebdriver } from 'creevey/playwright';
+
+const config: CreeveyConfig = {
+  webdriver: SeleniumWebdriver, // or PlaywrightWebdriver
+  browsers: {
+    chrome: {
+      // For Selenium
+      browserName: 'chrome',
+      seleniumCapabilities: {
+        browserVersion: '90.0',
+        platformName: 'linux',
+      },
+    },
+    firefoxPlaywright: {
+      // For Playwright
+      browserName: 'firefox', // 'chromium', 'firefox', or 'webkit' for Playwright
+      playwrightOptions: {
+        headless: true,
+      },
+    },
+  },
+};
+
+export default config;
+```
+
+### 2. Mocha Removal and New `CreeveyTestContext` API
+
+Creevey no longer uses the Mocha testing framework. Tests now use a `CreeveyTestContext` object passed as an argument to the test function.
+
+- Replace `this` with the `context` parameter in your tests.
+- Image matching methods (e.g., `matchImage`, `takeScreenshot`) are now called on the `context` object.
+- The `context.webdriver` property gives you direct access to the configured WebDriver instance (Selenium or Playwright) for advanced browser interactions.
+
+**Before (0.9 - Mocha style):**
+
+```javascript
+it('should match the image', async function () {
+  this.expect(await this.takeScreenshot()).to.matchImage('example');
+});
+```
+
+**After (0.10 - New context style):**
+
+```javascript
+it('should match the image', async (context) => {
+  await context.matchImage(await context.takeScreenshot(), 'example');
+});
+
+// Example using context.webdriver with Selenium WebDriver API
+it('should interact with an element using Selenium', async (context) => {
+  const seleniumWebDriver = context.webdriver; // Assuming SeleniumWebdriver is configured
+  const element = await seleniumWebDriver.findElement({ css: '#myElement' });
+  await element.click();
+  // ... more Selenium interactions
+  await context.matchImage(await context.takeScreenshot(), 'selenium-interaction');
+});
+
+// Example using context.webdriver with Playwright API
+it('should interact with an element using Playwright', async (context) => {
+  const playwrightPage = context.webdriver; // Assuming PlaywrightWebdriver is configured
+  await playwrightPage.click('#myElement');
+  // ... more Playwright interactions
+  await context.matchImage(await context.takeScreenshot(), 'playwright-interaction');
+});
+```
+
+### 3. Reporter Configuration
+
+Reporter setup has moved from command-line options to the `creevey.config.ts` file.
+
+**Example (0.10):**
+
+```typescript
+// creevey.config.ts
+import type { CreeveyConfig } from 'creevey';
+
+const config: CreeveyConfig = {
+  reporter: 'junit', // or 'teamcity', 'creevey'
+  reporterOptions: {
+    // For JUnit: { outputFile: 'report.xml' }
+    // For Creevey HTML reporter (default): { reportDir: './report' }
+  },
+};
+
+export default config;
+```
+
+---
+
+## Key New Features & Updates
+
+- **Creevey Playwright Reporter:** Integrate Creevey's visual testing into your existing Playwright test suites. See `docs/playwright-reporter.md` for details.
+- **Approve Tests from Report UI (Update Mode):** Approve visual changes directly in the Creevey report UI. Run with `creevey --ui --update` (or `creevey --ui -u`).
+- **ODiff Image Comparison:** Use `odiff` for image comparison with the `--odiff` flag and `odiffOptions` in config.
+- **Easier Storybook Autostart:** Use `creevey -s` or `creevey --startStorybook` to automatically start Storybook. Creevey will find a free port if necessary.
+
+---
+
+## Other Notable Changes
+
+- **`--noDocker` Option:** A command-line flag to disable Docker, overriding `useDocker: true` in your config.
+
+---
+
+We recommend reviewing the full announcement for details on all new features and improvements. After updating, test your suite thoroughly to ensure a smooth transition.

package/docs/playwright-reporter.md

@@ -0,0 +1,357 @@
+# Playwright Reporter for Creevey
+
+Creevey provides a Playwright-compatible reporter that allows you to use Creevey's image comparison, reporting, and UI features with Playwright tests.
+
+## Installation
+
+The reporter is included with the Creevey package. Install Playwright and Creevey in your project:
+
+```bash
+npm install --save-dev @playwright/test creevey
+```
+
+## Configuration
+
+Add the Creevey reporter to your Playwright configuration file:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    ['list'], // Standard Playwright reporter for console output
+    [
+      'creevey/playwright-reporter',
+      {
+        // Optional configuration options
+        reportDir: './report', // Directory for report output
+        screenDir: './images', // Directory for reference images
+        port: 3000, // Port for Creevey UI server
+        debug: false, // Enable debug logging
+      },
+    ],
+  ],
+  // Other Playwright configuration...
+});
+```
+
+## Usage
+
+### Taking Screenshots for Comparison
+
+The reporter automatically collects screenshots taken during Playwright tests. You can use Playwright's built-in screenshot capabilities:
+
+#### Using `page.screenshot()`
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('capture screenshot with page.screenshot', async ({ page }) => {
+  await page.goto('https://example.com');
+
+  // Take a screenshot and attach it to the test result
+  const screenshot = await page.screenshot();
+  await test.info().attach('example-screenshot', {
+    body: screenshot,
+    contentType: 'image/png',
+  });
+});
+```
+
+#### Using Playwright's expect().toHaveScreenshot()
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('capture screenshot with toHaveScreenshot', async ({ page }) => {
+  await page.goto('https://example.com');
+
+  // This will automatically be picked up by the Creevey reporter
+  await expect(page).toHaveScreenshot('example-screenshot.png');
+});
+```
+
+### Adding Creevey Metadata
+
+You can add metadata to your tests to better organize them in the Creevey UI:
+
+```typescript
+import { test } from '@playwright/test';
+
+test.describe('Homepage', () => {
+  test('header elements @creevey{"storyPath": ["Website", "HomePage"], "browser": "chromium"}', async ({ page }) => {
+    await page.goto('https://example.com');
+    // Test code...
+    await page.screenshot({ path: 'header.png' });
+  });
+});
+```
+
+The `@creevey` annotation accepts a JSON object with the following properties:
+
+- `storyPath`: Array of strings defining the hierarchy in the Creevey UI
+- `browser`: Browser name (chromium, firefox, webkit)
+- `testName`: Custom test name (defaults to the test title)
+
+### Viewing Results
+
+After running your tests, you can view the results in the Creevey UI:
+
+1. Open your browser and navigate to `http://localhost:3000` (or the port you configured)
+2. Browse test results, view image comparisons, and approve changes
+
+Run your tests with Playwright:
+
+```bash
+npx playwright test
+```
+
+The Creevey server will automatically start during the test run, and you'll see a message with the URL once tests complete.
+
+### Approving Screenshots
+
+You can approve screenshots directly from the Creevey UI by:
+
+1. Selecting the test with the failed comparison
+2. Reviewing the differences between expected and actual images
+3. Clicking the "Approve" button to update the reference image
+
+## Advanced Usage
+
+### Custom Screenshot Names
+
+You can customize screenshot names to better organize your visual tests:
+
+```typescript
+test('product page layout', async ({ page }) => {
+  await page.goto('https://example.com/products/1');
+
+  // Take multiple screenshots in a single test
+  await test.info().attach('product-header', {
+    body: await page.locator('.product-header').screenshot(),
+    contentType: 'image/png',
+  });
+
+  await test.info().attach('product-details', {
+    body: await page.locator('.product-details').screenshot(),
+    contentType: 'image/png',
+  });
+});
+```
+
+### Multiple Screenshots in One Test
+
+You can capture multiple screenshots in a single test:
+
+```typescript
+test('responsive design checks', async ({ page }) => {
+  await page.goto('https://example.com');
+
+  // Mobile view
+  await page.setViewportSize({ width: 375, height: 667 });
+  await test.info().attach('mobile-view', {
+    body: await page.screenshot(),
+    contentType: 'image/png',
+  });
+
+  // Tablet view
+  await page.setViewportSize({ width: 768, height: 1024 });
+  await test.info().attach('tablet-view', {
+    body: await page.screenshot(),
+    contentType: 'image/png',
+  });
+
+  // Desktop view
+  await page.setViewportSize({ width: 1280, height: 800 });
+  await test.info().attach('desktop-view', {
+    body: await page.screenshot(),
+    contentType: 'image/png',
+  });
+});
+```
+
+### Custom Test Names
+
+By default, the reporter will use the Playwright test title as the test name. You can customize how tests are named by setting meta data:
+
+```typescript
+test('home page visual test', async ({ page }) => {
+  test.info().annotations.push({
+    type: 'creevey',
+    description: JSON.stringify({
+      testName: 'custom-test-name',
+      browser: 'chrome', // Optional, to override browser name
+    }),
+  });
+
+  // Test implementation...
+});
+```
+
+### Integration with Existing Creevey Configuration
+
+If you're already using Creevey for other tests, you can share configuration:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+import creeveyConfig from './creevey.config.js';
+
+export default defineConfig({
+  reporter: [
+    ['list'],
+    [
+      'creevey/playwright-reporter',
+      {
+        reportDir: creeveyConfig.reportDir,
+        screenDir: creeveyConfig.screenDir,
+        port: 3001, // Use a different port to avoid conflicts
+      },
+    ],
+  ],
+});
+```
+
+### Test Steps Integration
+
+The reporter supports Playwright's test steps, capturing screenshots at each step:
+
+```typescript
+test('multi-step test', async ({ page }) => {
+  await test.step('Step 1: Navigate to home', async () => {
+    await page.goto('/');
+    // Screenshot captured from this step will be associated with "Step 1"
+    await test.info().attach('step1', {
+      body: await page.screenshot(),
+      contentType: 'image/png',
+    });
+  });
+
+  await test.step('Step 2: Click button', async () => {
+    await page.click('.button');
+    // This screenshot will be associated with "Step 2"
+    await test.info().attach('step2', {
+      body: await page.screenshot(),
+      contentType: 'image/png',
+    });
+  });
+});
+```
+
+### Integration with Existing Creevey Server
+
+If you're already running a Creevey server, you can configure the reporter to use it:
+
+```typescript
+[
+  CreeveyPlaywrightReporter,
+  {
+    useExistingServer: true, // Don't start a new server
+    port: 3000, // Port of the existing server
+  },
+];
+```
+
+### Performance Optimization
+
+For large test suites with many screenshots, you can enable performance optimizations:
+
+```typescript
+[
+  CreeveyPlaywrightReporter,
+  {
+    batchProcessing: true, // Process screenshots in batches
+    maxConcurrency: 4, // Maximum concurrent screenshot processing
+    lazyInit: true, // Initialize components on demand
+  },
+];
+```
+
+## API Reference
+
+### Reporter Options
+
+| Option                    | Type    | Default      | Description                                           |
+| ------------------------- | ------- | ------------ | ----------------------------------------------------- |
+| `reportDir`               | string  | `'./report'` | Directory where Creevey will store reports            |
+| `screenDir`               | string  | `'./images'` | Directory where reference images are stored           |
+| `port`                    | number  | `3000`       | Port number for the Creevey UI server                 |
+| `debug`                   | boolean | `false`      | Enable debug logging                                  |
+| `uiEnabled`               | boolean | `true`       | Enable or disable the UI server                       |
+| `useExistingServer`       | boolean | `false`      | Use an existing Creevey server instance               |
+| `batchProcessing`         | boolean | `false`      | Process screenshots in batches for better performance |
+| `maxConcurrency`          | number  | `2`          | Maximum concurrent screenshot processing operations   |
+| `lazyInit`                | boolean | `false`      | Initialize components on demand for faster startup    |
+| `retainOrphanedImages`    | boolean | `false`      | Keep images not associated with current tests         |
+| `customComparisonOptions` | object  | `undefined`  | Custom options for image comparison                   |
+
+## Troubleshooting
+
+### Common Issues
+
+- **Port conflicts**: If the Creevey server fails to start, it might be due to port conflicts. Change the port in the configuration.
+- **Missing screenshots**: Ensure your tests are attaching screenshots with unique names or using `toHaveScreenshot()`.
+- **Path issues**: If reference images aren't found, check that the `screenDir` path is correct and accessible.
+
+If screenshots are not appearing in the Creevey UI:
+
+1. Ensure your screenshots are being properly attached to test results
+2. Check that the content type is set to 'image/png' when attaching
+3. Enable debug mode in the reporter configuration to see detailed logs
+
+### Server Issues
+
+If the Creevey server fails to start:
+
+1. Check if the configured port is already in use
+2. Ensure the report directory is writable
+3. Look for error messages in the console output
+
+### Debug Mode
+
+Enable debug logging for more detailed information:
+
+```typescript
+[
+  CreeveyPlaywrightReporter,
+  {
+    debug: true,
+    // Other options...
+  },
+];
+```
+
+## Error Handling
+
+The reporter is designed to handle errors gracefully:
+
+- If the reporter fails to initialize, tests will still run and screenshots will be captured when possible
+- If the server can't start, the reporter will continue to capture screenshots but the UI won't be available
+- All errors are logged with appropriate severity levels and won't cause your tests to fail
+
+### Debugging Reporter Issues
+
+For detailed debugging information, enable debug mode and check the logs:
+
+```typescript
+[
+  CreeveyPlaywrightReporter,
+  {
+    debug: true,
+  },
+];
+```
+
+You can also specify a custom log file for the reporter:
+
+```typescript
+[
+  CreeveyPlaywrightReporter,
+  {
+    debug: true,
+    logFile: './creevey-reporter.log',
+  },
+];
+```
+
+For more help, please check the main Creevey documentation or open an issue on GitHub.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "creevey",
   "description": "Cross-browser screenshot testing tool for Storybook with fancy UI Runner",
-  "version": "0.10.0-beta.43",
+  "version": "0.10.0-beta.45",
   "type": "commonjs",
   "bin": "dist/cli.js",
   "main": "./dist/index.js",
@@ -12,6 +12,10 @@
       "types": "./dist/playwright.d.ts",
       "default": "./dist/playwright.js"
     },
+    "./playwright-reporter": {
+      "types": "./dist/playwright-reporter.d.ts",
+      "default": "./dist/playwright-reporter.js"
+    },
     "./selenium": {
       "types": "./dist/selenium.d.ts",
       "default": "./dist/selenium.js"
@@ -48,7 +52,8 @@
     "lint:tsc": "tsc --noEmit",
     "lint:eslint": "eslint",
     "lint:prettier": "prettier --check .",
-    "test": "vitest",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "start": "concurrently \"yarn start:client\" \"yarn start:storybook\" \"yarn start:creevey\"",
     "start:client": "vite",
     "start:storybook": "storybook dev --ci -p 6006",
@@ -86,16 +91,10 @@
     }
   },
   "dependencies": {
-    "@koa/cors": "^5.0.0",
     "@octokit/core": "^6.1.4",
     "@storybook/icons": "^1.4.0",
     "@types/chai": "^4.3.20",
     "@types/dockerode": "^3.3.37",
-    "@types/koa": "^2.15.0",
-    "@types/koa-bodyparser": "^4.3.12",
-    "@types/koa-mount": "^4.0.5",
-    "@types/koa-static": "^4.0.4",
-    "@types/koa__cors": "^5.0.0",
     "@types/lodash": "^4.17.16",
     "@types/micromatch": "^4.0.9",
     "@types/minimist": "^1.2.5",
@@ -113,10 +112,6 @@
     "dockerode": "^4.0.5",
     "find-cache-dir": "^5.0.0",
     "get-port": "^7.1.0",
-    "koa": "^2.16.0",
-    "koa-bodyparser": "^4.4.1",
-    "koa-mount": "^4.0.0",
-    "koa-static": "^5.0.0",
     "lodash": "^4.17.21",
     "loglevel": "^1.9.2",
     "loglevel-plugin-prefix": "^0.8.4",
@@ -140,6 +135,7 @@
   "devDependencies": {
     "@chromatic-com/storybook": "^3.2.6",
     "@eslint/js": "^9.23.0",
+    "@playwright/test": "^1.52.0",
     "@storybook/addon-essentials": "^8.6.12",
     "@storybook/addon-interactions": "^8.6.12",
     "@storybook/blocks": "^8.6.12",
@@ -208,7 +204,7 @@
     "displayName": "Creevey"
   },
   "volta": {
-    "node": "20.16.0",
-    "yarn": "4.4.0"
+    "node": "22.15.0",
+    "yarn": "4.9.1"
   }
 }

package/src/client/addon/controller.ts

@@ -22,7 +22,7 @@ export class CreeveyController {
   storyId = '';
   activeBrowser = '';
   selectedTestId = '';
-  status: CreeveyStatus = { isRunning: false, tests: {}, browsers: [] };
+  status: CreeveyStatus = { isRunning: false, tests: {}, browsers: [], isUpdateMode: false };
   creeveyApi: CreeveyClientApi | null = null;
   stories: StoriesRaw = {};
 

package/src/client/addon/withCreevey.ts

@@ -1,4 +1,4 @@
-import type { Renderer, StoryContextForEnhancers } from '@storybook/types';
+import type { Renderer } from '@storybook/types';
 import type { PreviewWeb, StoryStore } from '@storybook/preview-api';
 import { Channel } from '@storybook/channels';
 import {
@@ -121,7 +121,6 @@ function initCreeveyState(): void {
 
   if (prevState.creeveyHost) window.__CREEVEY_SERVER_HOST__ = prevState.creeveyHost;
   if (prevState.creeveyPort) window.__CREEVEY_SERVER_PORT__ = prevState.creeveyPort;
-  if (prevState.setStoriesCounter) setStoriesCounter = prevState.setStoriesCounter;
   if (prevState.isTestBrowser) isTestBrowser = prevState.isTestBrowser;
 
   window.addEventListener('beforeunload', () => {
@@ -130,7 +129,6 @@ function initCreeveyState(): void {
       JSON.stringify({
         creeveyHost: window.__CREEVEY_SERVER_HOST__,
         creeveyPort: window.__CREEVEY_SERVER_PORT__,
-        setStoriesCounter,
         isTestBrowser,
       } as CreeveyTestsState),
     );
@@ -141,7 +139,6 @@ let isTestBrowser = false;
 let captureResolver: () => void;
 let waitForCreevey: Promise<void>;
 let creeveyReady: () => void;
-let setStoriesCounter = 0;
 let globals = {};
 
 export function withCreevey(): ReturnType<typeof makeDecorator> {
@@ -160,20 +157,9 @@ export function withCreevey(): ReturnType<typeof makeDecorator> {
     document.head.appendChild(style);
   }
 
+  // TODO Find a way to send stories updates to the server
   async function getStories(): Promise<StoriesRaw | undefined> {
     const stories = serializeRawStories(await window.__STORYBOOK_PREVIEW__.extract());
-    const storiesByFiles = new Map<string, StoryContextForEnhancers[]>();
-    Object.values(stories).forEach((story) => {
-      const fileName = story.parameters.fileName as string;
-      const storiesFromFile = storiesByFiles.get(fileName);
-      if (storiesFromFile) storiesFromFile.push(story);
-      else storiesByFiles.set(fileName, [story]);
-    });
-    void fetch(`http://${getConnectionUrl()}/stories`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ setStoriesCounter, stories: [...storiesByFiles.entries()] }),
-    });
     return stories;
   }
 

package/src/client/shared/components/PageHeader/PageHeader.tsx

@@ -21,14 +21,14 @@ interface PageHeaderProps {
 }
 
 const Container = styled.div({
-  margin: '24px 44px 0',
+  marginTop: '24px',
 });
 
 const ErrorContainer = withTheme(
   styled.div<{ theme: Theme }>(({ theme }) => ({
     marginTop: '8px',
     padding: '8px',
-    background: theme.background.negative,
+    background: `${theme.background.negative}20`,
     color: theme.color.negative,
     borderRadius: '2px',
     display: 'flex',
@@ -48,8 +48,19 @@ const ErrorContainer = withTheme(
   })),
 );
 
+const UpdateModeBanner = withTheme(
+  styled.div(({ theme }) => ({
+    padding: '8px 32px',
+    backgroundColor: `${theme.color.positive}20`,
+    color: theme.color.positive,
+    fontSize: '12px',
+    textAlign: 'center',
+    fontWeight: 'bold',
+  })),
+);
+
 const H1 = styled.h1({
-  margin: 0,
+  marginLeft: '44px',
   marginBottom: '8px',
 });
 
@@ -77,7 +88,7 @@ export function PageHeader({
   onImageChange,
   onViewModeChange,
 }: PageHeaderProps): JSX.Element | null {
-  const { isReport } = useContext(CreeveyContext);
+  const { isReport, isUpdateMode } = useContext(CreeveyContext);
   const imageEntires = Object.entries(images) as [string, Images][];
 
   const handleViewModeChange = (mode: string): void => {
@@ -120,6 +131,9 @@ export function PageHeader({
           ))}
         </ImagesEntriesContainer>
       ) : null}
+      {isUpdateMode && (
+        <UpdateModeBanner>Update Mode: Review and approve screenshots from previous test runs</UpdateModeBanner>
+      )}
       {showViewModes && (
         <Tabs selected={viewMode} actions={{ onSelect: handleViewModeChange }}>
           {viewModes.map((x) => (