┌─────────────────────────────────────────────────────────────────────┐
│                        playwright.config.js                         │
│  createConfig({ appDir, port })                                     │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
          ┌────────────────────┼────────────────────┐
          │                    │                    │
          ▼                    ▼                    ▼
    Phase 1: BUILD      Phase 2: FIXTURES     Phase 3: TESTS
    (before tests)      (Playwright setup)    (your test code)

NEXT_PUBLIC_LOWDEFY_E2E=true npx lowdefy build && npx lowdefy start

{
  "pages": {
    "contact": {
      "name_input": {
        "type": "TextInput",
        "helper": "@lowdefy/blocks-antd/e2e/TextInput"
      }
    }
  }
}

Worker scope (shared across tests):
┌──────────────────────────────────────────────────────────────┐
│  manifest          Loads e2e-manifest.json                   │
│  helperRegistry    Lazy-loading cache for block e2e modules  │
│  staticMocks       Loads mocks.yaml once                     │
└──────────────────────────────────────────────────────────────┘

Test scope (fresh per test):
┌──────────────────────────────────────────────────────────────┐
│  ldf               Main test API (createPageManager)         │
│  mockManager       Per-test route handlers                   │
└──────────────────────────────────────────────────────────────┘

ldf.block('id').do.fill('value'); // Block actions
ldf.block('id').expect.visible(); // Block assertions
ldf.request('id').expect.toFinish(); // Request assertions
ldf.state('key').expect.toBe(value); // State assertions
ldf.mock.request('id', { response }); // Inline mocking

createConfig({ appDir, port, timeout, ... })      // Single app
createMultiAppConfig({ apps: [...] })             // Monorepo

// Navigation
ldf.goto('/path')                          // Navigate and wait for Lowdefy ready
ldf.waitForPage('/path')                   // Wait for URL change + Lowdefy ready
ldf.pageId                                 // Current page ID (getter)
ldf.page                                   // Raw Playwright page object

// Block
ldf.block('id')                            // Returns block locator object
  .do.fill('value')                        // Action methods (type-specific)
  .expect.visible()                        // Assertion methods
  .locator()                               // Raw Playwright locator
  .state()                                 // Block's state value
  .validation()                            // Block's validation object

// Request
ldf.request('id')                          // Returns request locator object
  .expect.toFinish(opts?)                  // Wait for loading: false
  .expect.toHaveResponse(data, opts?)      // Assert partial response match
  .expect.toHavePayload(data, opts?)       // Assert partial payload match
  .response()                              // Raw response data
  .state()                                 // Full request state object

// State
ldf.state('key')                           // Returns state locator object
  .do.set(value)                           // Set state value
  .expect.toBe(value, opts?)               // Assert state value
  .value()                                 // Get raw value
ldf.state()                                // No key: returns { value() } for full state

// URL
ldf.url()                                  // Returns URL locator object
  .expect.toBe('/path', opts?)             // Assert exact path
  .expect.toMatch(/pattern/, opts?)        // Assert regex match
  .value()                                 // Get current URL string

// URL Query
ldf.urlQuery('key')                        // Returns query param locator
  .do.set('value')                         // Set query parameter
  .expect.toBe('value', opts?)             // Assert query parameter value
  .value()                                 // Get current value

// Mocking
ldf.mock.request('id', { response, error, pageId })  // Mock request
ldf.mock.api('id', { response, error, method })       // Mock API endpoint
ldf.mock.getCapturedRequest('id')                      // Get captured { payload, timestamp }
ldf.mock.clearCapturedRequests()                       // Clear captured payloads

import { createBlockHelper } from '@lowdefy/e2e-utils';
import { expect } from '@playwright/test';

const locator = (page, blockId) => page.locator(`#${blockId}_input`);

export default createBlockHelper({
  locator,
  do: {
    fill: (page, blockId, val) => locator(page, blockId).fill(val),
  },
  get: {
    value: (page, blockId) => locator(page, blockId).inputValue(),
  },
  expect: {
    // visible, hidden, disabled, enabled, validationError auto-provided
    value: (page, blockId, val) => expect(locator(page, blockId)).toHaveValue(val),
  },
});

// createHelperRegistry.js
import { createRequire } from 'module';

const serverRequire = createRequire(path.join(serverDir, 'package.json'));
const resolvedPath = serverRequire.resolve('@lowdefy/blocks-antd/e2e/TextInput');

requests:
  - requestId: atlas_search
    response: [{ _id: 'doc-1' }]
  - requestId: fetch_* # Wildcards supported
    pageId: admin-*
    response: []
api:
  - endpointId: external_api
    method: POST
    response: { status: ok }

await ldf.mock.request('search', { response: [] });
await ldf.mock.request('fetch', { error: 'Not found' });
await ldf.mock.api('external', { response: { ok: true } });

# Static error mock
requests:
  - requestId: atlas_search
    error: Atlas Search not available in test

await ldf.mock.api('webhook', { method: 'POST', response: { ok: true } });
// GET /api/endpoints/webhook passes through to real server
// POST /api/endpoints/webhook returns mocked response

await ldf.mock.request('search', { response: [] });
await ldf.block('search_btn').do.click();

const captured = ldf.mock.getCapturedRequest('search');
// { payload: { query: 'widget' }, timestamp: 1707600000000 }

ldf.mock.clearCapturedRequests();

await ldf.user({ id: 'test', name: 'Test', roles: ['admin'] }); // Set user
await ldf.user(null); // Clear user

user:
  name: Test User
  email: [email protected]
  roles:
    - admin

// blocks-antd/package.json
{
  "exports": {
    "./e2e/TextInput": "./dist/blocks/TextInput/e2e.js",
    "./e2e/Button": "./dist/blocks/Button/e2e.js"
  }
}

await ldf.request('id').expect.toFinish({ timeout: 60000 });
await ldf.state('key').expect.toBe(value, { timeout: 10000 });

src/
├── index.js                    # Main exports
├── config.js                   # createConfig, createMultiAppConfig
├── core/
│   ├── index.js
│   ├── locators.js
│   ├── navigation.js
│   ├── requests.js
│   ├── state.js
│   ├── url.js
│   └── validation.js
├── fixtures/
│   └── index.js                # Playwright test.extend()
├── init/
│   ├── index.js                # CLI entry
│   ├── detectApps.js
│   ├── generateFiles.js
│   ├── updateGitignore.js
│   └── templates/
│       ├── playwright.config.js.template
│       ├── example.spec.js.template
│       ├── fixtures.js.template
│       ├── mocks.yaml.template
│       ├── mongodb.spec.js.template
│       ├── env.e2e.template
│       └── README.md.template
├── mocking/
│   ├── index.js
│   ├── createMockManager.js
│   └── loadStaticMocks.js
├── proxy/
│   ├── createBlockHelper.js
│   ├── createBlockMethodProxy.js
│   ├── createHelperRegistry.js
│   └── createPageManager.js
└── testPrep/
    ├── extractBlockMap.js
    └── generateManifest.js

@lowdefy/blocks-antd    # Block e2e helpers
@lowdefy/blocks-basic   # Block e2e helpers
js-yaml                 # Parse mocks.yaml
prompts                 # CLI prompts

peerDependencies:
@playwright/test        # Testing framework