DarkLens Playwright Plugin 🎭

Automated E2E assertions for Dark Patterns & Deceptive UX inside Playwright test suites.

Catch deceptive checkout traps, pre-checked auto-renewal checkboxes, roach motel cancellations, and regulatory non-compliance (GDPR, FTC Act Sec. 5, CCPA, EU DSA) directly in your Playwright End-to-End tests before shipping to production.

⚡ Installation

npm install --save-dev darklens-playwright

🚀 Quick Usage

Option 1: Native Custom Matcher (toHaveNoDarkPatterns)

import { test, expect } from '@playwright/test';
import 'darklens-playwright/extend-expect';

test('checkout flow is dark pattern free', async ({ page }) => {
  await page.goto('https://staging.myapp.com/checkout');

  // One line of code: Instantly turns test red if dark patterns are detected!
  await expect(page).toBeDarkPatternFree();
});

Option 2: Function Assertion (assertNoDarkPatterns)

import { test } from '@playwright/test';
import { assertNoDarkPatterns } from 'darklens-playwright';

test('user cancellation settings are compliant', async ({ page }) => {
  await page.goto('https://staging.myapp.com/account/settings');
  await page.click('button#cancel-plan');

  // Captures live dynamic modal DOM and verifies cancellation is click-to-cancel compliant
  await assertNoDarkPatterns(page, {
    threshold: 70,
    failOn: 'critical', // Only fails if critical legal violations are found
  });
});

🔑 Authentication

Set the DARKLENS_API_KEY environment variable in your CI/CD runner or .env:

export DARKLENS_API_KEY="your_api_key_here"

Or pass it directly in test options:

await assertNoDarkPatterns(page, {
  apiKey: 'your_api_key_here',
  threshold: 80,
});

Get your API key in the DarkLens Dashboard.

🛠️ Configuration Options

| Option | Type | Default | Description | | :--- | :---: | :---: | :--- | | threshold | number | 70 | Minimum passing score (0–100). | | failOn | 'score' \| 'critical' \| 'any' | 'score' | Failure condition. | | apiKey | string | $DARKLENS_API_KEY | DarkLens API Key. | | captureSnapshot | boolean | true | When true, sends the live DOM snapshot. Allows auditing authenticated dashboards, modals, and local dev servers. |

📄 License

MIT © DarkLens