Pixeleye

https://pixeleye.io/docs/
Admin
Pixeleye is an open-source, self-hostable, all-in-one visual test and review platform that allows...
Tokens:10,247
Snippets:152
Trust Score:6.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Pixeleye CLI with NPM

Source: https://pixeleye.io/docs/integrations/any-other-platform-%28cli%29

Install the Pixeleye CLI as a development dependency using NPM.

```bash
npm install pixeleye --save-dev  
```

--------------------------------

### Install Pixeleye and Puppeteer

Source: https://pixeleye.io/docs/integrations/puppeteer

Install the Pixeleye CLI and Puppeteer as development dependencies using npm.

```bash
npm install pixeleye @pixeleye/puppeteer --save-dev  

```

--------------------------------

### Storybook Variant Example

Source: https://pixeleye.io/docs/integrations/config

Example of configuring Storybook variants for screenshot capture. This demonstrates how to specify different themes by appending query parameters to the Storybook URL.

```javascript
[{ name: "Dark", params: "?globals=theme:dark" }, { name: "Light", params: "?globals=theme:light" }]
```

--------------------------------

### Install Pixeleye Cypress Plugin

Source: https://pixeleye.io/docs/integrations/cypress

Install the Pixeleye CLI tool and the Cypress integration package as development dependencies using NPM, PNPM, or Yarn.

```bash
npm install pixeleye @pixeleye/cypress --save-dev  
  
  

```

--------------------------------

### Install Pixeleye and Playwright

Source: https://pixeleye.io/docs/integrations/playwright

Install the necessary Pixeleye and Playwright packages as development dependencies using npm.

```bash
npm install pixeleye @pixeleye/playwright --save-dev  
```

--------------------------------

### Run Pixeleye CLI with Storybook

Source: https://pixeleye.io/docs/integrations/storybook

Execute the Pixeleye CLI to capture your Storybook instance. This command starts Storybook and then runs the Pixeleye capture process.

```bash
npm run storybook & pixeleye storybook http://localhost:6006  

```

--------------------------------

### Playwright Example with Pixeleye Sharding

Source: https://pixeleye.io/docs/guides/parallel-tests

Example demonstrating how to run Playwright tests in parallel using Pixeleye's sharding. This command sets the shard count to 3 and the current shard ID to 1, passing the shard information to Playwright.

```bash
pixeleye exec --count 3 --shard 1 -- npx playwright test --shard=1/3
```

```bash
pixeleye exec --count 3 --shard 1 -- npx playwright test --shard=1/3
```

--------------------------------

### Basic GitHub Actions Workflow for Pixeleye

Source: https://pixeleye.io/docs/ci/github-actions

This workflow configures a GitHub Actions job to run Pixeleye. It checks out the code, sets up Node.js, installs dependencies, and then executes both Storybook and Pixeleye CLI commands. Ensure your PIXELEYE_PROJECT_TOKEN is set in your GitHub secrets.

```yaml
name: "Pixeleye"

on:
  push:
    branches: ["main"]
  pull_request:
    types: [opened, synchronize]

jobs:
  pixeleye:
    runs-on: ubuntu-latest
    env:
      PIXELEYE_PROJECT_TOKEN: ${{ secrets.PIXELEYE_PROJECT_TOKEN }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Use Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependencies
        run: npm install
      - name: Capture stories with Pixeleye CLI
        # Running Pixeleye against your storybook
        run: npm run storybook & npm run pixeleye storybook

```

--------------------------------

### Add Storybook Script to package.json

Source: https://pixeleye.io/docs/integrations/storybook

Add a script to your package.json to easily start Storybook and run the Pixeleye capture command.

```json
{
  "scripts": {
    "storybook": "start-storybook -p 6006",
    "pixeleye": "npm run storybook & pixeleye storybook http://localhost:6006"
  }
}

```

--------------------------------

### Upload Directory of Images using CLI

Source: https://pixeleye.io/docs/integrations/any-other-platform-%28cli%29

Use the Pixeleye CLI to upload a directory of screenshots. Ensure screenshots are in PNG format and follow the naming convention `{name}--{variant}.png` for metadata.

```bash
pixeleye upload ./path/to/screenshots  
```

--------------------------------

### Configure Pixeleye Project Token (JavaScript)

Source: https://pixeleye.io/docs/integrations/any-other-platform-%28cli%29

Configure the Pixeleye CLI with your project token in a JavaScript configuration file. The token can be hardcoded or read from an environment variable.

```javascript
/** @type {import('pixeleye').Config} */  
const config = {  
  token: "YOUR_PROJECT_TOKEN",  
  // or  
  // token: process.env.PIXELEYE_PROJECT_TOKEN,  
  // ...  
};
  
export default config;  
  
```

--------------------------------

### Run Pixeleye CLI Command

Source: https://pixeleye.io/docs/integrations/puppeteer

Execute your test commands using the Pixeleye CLI via npm scripts.

```bash
npm run pixeleye exec -- <your test command>  

```

--------------------------------

### Run Cypress Tests with Pixeleye CLI

Source: https://pixeleye.io/docs/integrations/cypress

Execute Cypress tests using the Pixeleye CLI by passing the `cypress run` command to `npm run pixeleye exec`.

```bash
npm run pixeleye exec -- cypress run  
  
  

```

--------------------------------

### Run Pixeleye CLI with Playwright Tests

Source: https://pixeleye.io/docs/integrations/playwright

Execute your Playwright tests using the Pixeleye CLI to initiate snapshot comparisons and analysis.

```bash
npm run pixeleye exec -- <your test command>  
  
```

--------------------------------

### Basic Pixeleye Configuration

Source: https://pixeleye.io/docs/integrations/config

A basic configuration object for Pixeleye, specifying the project token. It shows how to directly embed the token or use an environment variable.

```javascript
const config = {
  token: "YOUR_PROJECT_TOKEN",
  // or
  // token: process.env.PIXELEYE_PROJECT_TOKEN,
  // ...
};

export default config;

```

--------------------------------

### Docker Compose for Self-Hosting Pixeleye

Source: https://pixeleye.io/docs/guides/self-hosting

This Docker Compose file is used to set up Pixeleye, including its backend, frontend, and database migrations. Ensure the './config' folder is in the same directory.

```yaml
version: "3.8"

services:
  pixeleye:
    image: ghcr.io/ory/pixeleye:latest
    container_name: pixeleye
    ports:
      - "3000:3000"
    environment:
      - "PIXELEYE_URL=http://localhost:3000"
      - "DATABASE_URL=postgres://user:password@db:5432/pixeleye?sslmode=disable"
      - "RABBITMQ_CONNECTION=amqp://user:password@rabbitmq:5672/"
      - "SMTP_FROM=noreply@pixeleye.com"
      - "SMTP_HOST=mailslurper"
      - "SMTP_PORT=1025"
      - "SMTP_USERNAME="
      - "SMTP_PASSWORD= "
      - "SMTP_USE_TLS=false"
      - "JWT_SECRET=changeme"
      - "COOKIE_SECRET=changeme"
      - "KRATOS_BROWSER_URL=http://localhost:4433"
      - "KRATOS_ADMIN_URL=http://kratos:4434"
      - "KRATOS_PUBLIC_API_URL=http://localhost:4433"
      - "KRATOS_ADMIN_API_URL=http://kratos:4434"
      - "GITHUB_CLIENT_ID=changeme"
      - "GITHUB_CLIENT_SECRET=changeme"
    depends_on:
      - db
      - rabbitmq
      - mailslurper
      - kratos

  db:
    image: postgres:14
    container_name: pixeleye-db
    volumes:
      - pixeleye-db:/var/lib/postgresql/data
    environment:
      - "POSTGRES_USER=user"
      - "POSTGRES_PASSWORD=password"
      - "POSTGRES_DB=pixeleye"

  rabbitmq:
    image: rabbitmq:3-management
    container_name: pixeleye-rabbitmq
    environment:
      - "RABBITMQ_DEFAULT_USER=user"
      - "RABBITMQ_DEFAULT_PASS=password"

  mailslurper:
    image: mailslurper/mailslurper:latest
    container_name: pixeleye-mailslurper
    ports:
      - "4437:80"

  kratos:
    image: ghcr.io/ory/kratos:latest
    container_name: pixeleye-kratos
    ports:
      - "4433:4433"
      - "4434:4434"
    volumes:
      - ./config:/etc/config
    command: serve -c /etc/config/kratos.yml --dev

volumes:
  pixeleye-db:

```

--------------------------------

### Capture Screenshots from Sitemap

Source: https://pixeleye.io/docs/integrations/sitemaps-and-urls

Use the Pixeleye CLI to capture screenshots by providing a sitemap URL.

```bash
npm run pixeleye snapshot --sitemaps https://example.com/sitemap.xml  
```

--------------------------------

### fn pixeleyeSnapshot(options)

Source: https://pixeleye.io/docs/integrations/cypress

Captures a snapshot of the current page using Cypress. This command allows for detailed configuration of the snapshot process, including naming, variants, full-page capture, element selection, and device emulation.

```APIDOC
## `pixeleyeSnapshot(options)`

### Description
Captures a snapshot of the current page. This command is used within Cypress tests to integrate with Pixeleye for visual regression testing.

### Method
`cy.pixeleyeSnapshot(options)`

### Parameters
#### Options
- **name** (string) - Required - The name of the snapshot. This is used for identification and comparison in the Pixeleye dashboard.
- **variant** (string) - Optional - The variant of the snapshot. Useful for capturing different states of the same component (e.g., 'primary', 'secondary'). Defaults to `undefined`.
- **fullPage** (boolean) - Optional - Whether to capture the full page. Defaults to `false` (captures current viewport).
- **selector** (string) - Optional - The CSS selector of the element to capture. If provided, only the specified element is captured. Defaults to `undefined` (captures the entire page).
- **waitForSelectors** (string[]) - Optional - An array of CSS selectors to wait for before capturing the snapshot. Defaults to `[]`.
- **devices** (DeviceDescriptor[]) - Optional - An array of device descriptors to capture the snapshot on. Overrides the `devices` option in `pixeleye.config.ts`. Defaults to devices defined in `pixeleye.config.ts`.
- **waitForStatus** (boolean) - Optional - If `true`, waits for the build processing to finish and returns the status to stdout. Useful for CI/CD. Defaults to `false`.
- **maskSelectors** (string[]) - Optional - An array of CSS selectors to mask in the snapshot. Defaults to `[]`.
- **maskColor** (string) - Optional - The CSS color to use for masking selectors. Defaults to `#FF00FF (pink)`.
- **css** (string) - Optional - Custom CSS to inject into the page for hiding elements or overriding styles. Appended to CSS from `pixeleye.config.ts`. Defaults to `undefined`.

### Request Example
```javascript
// Assuming cypress/support/e2e.ts has 'import "@pixeleye/cypress";'

// ...

await cy.pixeleyeSnapshot({
  name: "landing-header",
  variant: "default",
  fullPage: true,
  selector: ".main-content",
  waitForSelectors: ["#app-loaded"],
  devices: [
    { name: "Desktop", width: 1024, height: 768 },
    { name: "Mobile", width: 375, height: 667 }
  ],
  maskSelectors: [".sensitive-data"],
  maskColor: "#000000",
  css: ".cookie-banner { display: none; }"
});

// ...
```

### Response
This command does not return a value directly in the test, but it triggers a snapshot capture and comparison via the Pixeleye service. The `waitForStatus` option can provide build status information to stdout.
```

--------------------------------

### Capture Screenshots from a List of URLs

Source: https://pixeleye.io/docs/integrations/sitemaps-and-urls

Use the Pixeleye CLI to capture screenshots by providing a list of URLs.

```bash
npm run pixeleye snapshot --urls https://example.com/page1 https://example.com/page2  
```

--------------------------------

### Define URLs in a Pixeleye Configuration File (TypeScript)

Source: https://pixeleye.io/docs/integrations/sitemaps-and-urls

Define a list of URLs with potential options in a `*.pixeleye.ts` configuration file. This allows for more organized URL definitions.

```typescript
import {SnapshotDefinition} from "pixeleye";  
  
const urls: SnapshotDefinition[] = [  
  {
    url: "https://example.com/page1",  
    // options  
  },  
  {
    url: "https://example.com/page2",  
    // options  
  },  
  // ...  
];  
  
export default urls;  
  
```

--------------------------------

### Execute Pixeleye with Shard Count and ID

Source: https://pixeleye.io/docs/guides/parallel-tests

Use this command to execute tests in parallel. Specify the total number of shards and the current shard's ID. The `<test command>` is the command to run your tests.

```bash
pixeleye exec --count <count> --shard <shardID> -- <test command>
```

```bash
pixeleye exec --count <count> --shard <shardID> -- <test command>
```

--------------------------------

### Configure Pixeleye to Use Snapshot Definition Files

Source: https://pixeleye.io/docs/integrations/sitemaps-and-urls

Specify snapshot definition files in the `config.pixeleye.ts` file using glob patterns. This tells Pixeleye where to find your URL definitions.

```typescript
import { Config } from "pixeleye";  
  
const config: Config = {  
  ...  
  snapshotFiles: ["./**/*.pixeleye.ts"],  
};
  
export default config;  
  
```

--------------------------------

### Capture External Storybook Instance

Source: https://pixeleye.io/docs/integrations/storybook

Use the Pixeleye CLI to capture a Storybook instance hosted at a specific URL. This is useful for public Storybooks or those on different servers.

```bash
pixeleye storybook https://example.com/storybook  

```

--------------------------------

### Import Pixeleye into Cypress Support File

Source: https://pixeleye.io/docs/integrations/cypress

Import the Pixeleye Cypress plugin into your Cypress support file (e.g., cypress/support/e2e.ts) to enable Pixeleye commands.

```typescript
import "@pixeleye/cypress";  
  
  

```

--------------------------------

### Provide Dynamic URLs via a Function in Configuration

Source: https://pixeleye.io/docs/integrations/sitemaps-and-urls

Use a function within `config.pixeleye.ts` to dynamically generate a list of URLs for capturing screenshots. This is useful for lists that change frequently.

```typescript
import { Config, ConfigWithoutSnapshotFiles } from "pixeleye";  
  
const config: Config = {  
  ...  
  snapshotFiles: (config: ConfigWithoutSnapshotFiles) => {  
    return [  
      {
        url: "https://example.com/page1",  
        // options  
      },  
      {
        url: "https://example.com/page2",  
        // options  
      },  
      // ...  
    ];  
  },
};
  
export default config;  
  
```

--------------------------------

### Configure Storybook Variants for Dark/Light Mode

Source: https://pixeleye.io/docs/integrations/storybook

Define multiple variants for Storybook captures, such as dark and light modes, using the `storybookOptions.variants` in the Pixeleye configuration.

```javascript
/** @type {import('pixeleye').Config}*/  
const config = {  
  token: "YOUR_PROJECT_TOKEN",  
  storybookOptions: {  
    variants: [  
      {  
        name: "Dark",  
        params: "globals=theme:dark",  
      },  
      {  
        name: "Light",  
        params: "globals=theme:light",  
      },  
    ],  
  }
}

```

--------------------------------

### Add Pixeleye Snapshot to Cypress Test

Source: https://pixeleye.io/docs/integrations/cypress

Use the `cy.pixeleyeSnapshot()` command within your Cypress tests to capture visual snapshots of your application.

```typescript
  

// ...  
  
  await cy.pixeleyeSnapshot({  

    name: "landing-header",  

  });  

// ...  
  
  

```

--------------------------------

### Add Pixeleye Snapshot to Playwright Test

Source: https://pixeleye.io/docs/integrations/puppeteer

Import and use the `pixeleyeSnapshot` function within your Playwright tests to capture visual snapshots.

```typescript
import { pixeleyeSnapshot } from "@pixeleye/playwright";  

test("Some test", async () => {  

  // ...  

  await pixeleyeSnapshot(app.page, {  

    name: "button",  

  });  

  // ...  

});  

```

--------------------------------

### Add Pixeleye Snapshot to Playwright Test

Source: https://pixeleye.io/docs/integrations/playwright

Import and use the pixeleyeSnapshot function within your Playwright tests to capture visual snapshots.

```typescript
import { pixeleyeSnapshot } from "@pixeleye/playwright";  
  
test("Some test", async ({ page }) => {  
  // ...  
  await pixeleyeSnapshot(page, {  

    name: "button",  

  });  
  // ...  
});  
  
```

--------------------------------

### Skip Capturing a Specific Story

Source: https://pixeleye.io/docs/integrations/storybook

Configure individual stories to be skipped during the Pixeleye capture process by adding a `pixeleye.skip: true` parameter in the story's configuration.

```typescript
import type { Meta } from "@storybook/react";  
import type { StoryParams } from "pixeleye";  
import Button from "./button";  
  
const meta: Meta<typeof Button> & StoryParams = {  
  component: Button,  
  title: "UI/Button",  
  parameters: {  
    pixeleye: {  
      skip: true,  
    },  
  },  
};

```

--------------------------------

### pixeleyeSnapshot Function

Source: https://pixeleye.io/docs/integrations/puppeteer

The `pixeleyeSnapshot` function is used to capture a snapshot of a given page. It accepts the Puppeteer page object and an options object to configure the snapshot capture.

```APIDOC
## `pixeleyeSnapshot(page, options)`

Captures a snapshot of the current page.

### Parameters

#### Page

* **page** (`Page`) - Required - The page to capture the snapshot on. This is the page returned from `puppeteer.launch()`.

#### Options

* **name** (`string`) - Required - The name of the snapshot. This helps identify which snapshots to compare with as well as giving a nice name in our dashboard.
* **variant** (`string`) - Optional - The variant of the snapshot. Useful for capturing different states of the same component (e.g., `primary`, `secondary` buttons).
* **fullPage** (`boolean`) - Optional - Whether to capture the full page. Defaults to `false` (captures current viewport).
* **selector** (`string`) - Optional - The selector of the element to capture. If set, only the element matching the selector will be captured. If not set, the entire page will be captured.
* **waitForSelectors** (`string[]`) - Optional - An array of selectors to wait for before capturing the snapshot. Defaults to `[]`.
* **devices** (`DeviceDescriptor[]`) - Optional - An array of devices to capture the snapshot on. Overrides the `devices` option set in `pixeleye.config.ts`. Defaults to `Defined in pixeleye.config.ts`.
* **waitForStatus** (`boolean`) - Optional - If set to `true`, waits for the build to finish processing and returns the status of the build to stdout. Defaults to `false`.
* **maskSelectors** (`string[]`) - Optional - An array of selectors to mask. Defaults to `[]`.
* **maskColor** (`string`) - Optional - The color to mask the selectors with. Defaults to `#FF00FF (pink)`.
* **css** (`string`) - Optional - CSS to inject into the page to hide elements. This CSS is appended to the CSS defined in `pixeleye.config.ts`.
```

--------------------------------

### pixeleyeSnapshot Function

Source: https://pixeleye.io/docs/integrations/playwright

The `pixeleyeSnapshot` function is used within your Playwright tests to capture snapshots of the current page or specific elements. It allows for detailed configuration to control what is captured and how.

```APIDOC
## `fn pixeleyeSnapshot(page, options)`

Captures a snapshot of the current page.

### Parameters

#### Page
* **page** (`Page`) - Required - The page to capture the snapshot on.

#### Options
* **name** (`string`) - Required - The name of the snapshot. This helps identify snapshots for comparison and naming in the dashboard.
* **variant** (`string`) - Optional - The variant of the snapshot. Useful for capturing different states of the same component (e.g., `primary`, `secondary` for a button).
* **fullPage** (`boolean`) - Optional - Defaults to `false`. If `true`, captures the entire page; otherwise, captures only the current viewport.
* **selector** (`string`) - Optional - The selector of the element to capture. If set, only the element matching the selector is captured. If not set, the entire page is captured.
* **waitForSelectors** (`string[]`) - Optional - Defaults to `[]`. Selectors to wait for before capturing the snapshot. If set, waits for all specified selectors to appear.
* **devices** (`DeviceDescriptor[]`) - Optional - Defaults to `Defined in pixeleye.config.ts`. The devices to capture the snapshot on. Overrides the `devices` option in `pixeleye.config.ts`.
* **waitForStatus** (`boolean`) - Optional - Defaults to `false`. If `true`, waits for the build to finish processing and returns the status to stdout.
* **maskSelectors** (`string[]`) - Optional - Defaults to `[]`. Selectors to mask. These will be masked with the `maskColor`.
* **maskColor** (`string`) - Optional - Defaults to `#FF00FF (pink)`. The CSS color to mask the selectors with.
* **css** (`string`) - Optional - CSS to inject into the page to hide elements. Appended to CSS defined in `pixeleye.config.ts`.
```
Tokens:
Raw