@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/testing/e2e-getting-started.md

@@ -0,0 +1,96 @@
+# Getting Started
+
+## Setup
+
+The fastest way to set up e2e testing is with the scaffold command. Run this in your project root:
+
+```
+npx @lowdefy/e2e-utils
+```
+
+The command will:
+- Detect your Lowdefy app (single-app or multi-app)
+- Ask if you want MongoDB testing support
+- Create test files in an `e2e/` directory
+- Update your `package.json` with test scripts
+- Update `.gitignore` with test artifacts
+- Optionally install dependencies and Playwright browsers
+
+## Generated files
+
+After running the scaffold command, your project will have:
+
+```
+e2e/
+  playwright.config.js    # Playwright configuration
+  fixtures.js             # Test fixtures (provides the ldf helper)
+  mocks.yaml              # Static request mocks
+  example.spec.js         # Example test to get you started
+```
+
+## Running tests
+
+Run all tests:
+```
+pnpm e2e
+```
+
+Run tests with the Playwright UI (useful for debugging):
+```
+pnpm e2e:ui
+```
+
+> The first run will take longer because Playwright needs to build and start your Lowdefy app. Subsequent runs reuse the server if it is still running.
+
+## Your first test
+
+The generated `example.spec.js` looks like this:
+
+```javascript
+import { test, expect } from './fixtures.js';
+
+test('homepage loads', async ({ ldf }) => {
+  await ldf.goto('/');
+  await expect(ldf.page).toHaveTitle(/./);
+});
+```
+
+Let's break this down:
+
+- `import { test, expect } from './fixtures.js'` — imports the enhanced test function that provides the `ldf` helper
+- `test('...', async ({ ldf }) => { ... })` — the `ldf` object is automatically created for each test with a fresh browser page
+- `await ldf.goto('/')` — navigates to the homepage and waits for the Lowdefy client to initialize
+- `await expect(ldf.page).toHaveTitle(/./)` — uses the raw Playwright page to assert the page has a title
+
+## Writing a real test
+
+Here is a more practical example. Suppose you have a page with a search form:
+
+```javascript
+import { test } from './fixtures.js';
+
+test('search returns results', async ({ ldf }) => {
+  await ldf.goto('/search');
+
+  // Fill in the search input and click search
+  await ldf.block('search_input').do.fill('widget');
+  await ldf.block('search_btn').do.click();
+
+  // Wait for the request to complete
+  await ldf.request('search_products').expect.toFinish();
+
+  // Check that results appeared in state
+  const results = await ldf.state('search_results').value();
+  expect(results.length).toBeGreaterThan(0);
+});
+```
+
+## What happens behind the scenes
+
+When you run `pnpm e2e`:
+
+1. Playwright reads `playwright.config.js`, which uses `createConfig()` from `@lowdefy/e2e-utils/config`
+2. The config starts a web server that builds your app with the e2e server variant and starts it
+3. A manifest is generated from your build artifacts, mapping block IDs to their types and e2e helpers
+4. For each test, a fresh `ldf` object is created with a new browser page, and any static mocks from `mocks.yaml` are applied
+5. Your test code runs against the live app

package/content/testing/e2e-introduction.md

@@ -0,0 +1,53 @@
+# E2E Testing
+
+End-to-end (e2e) testing verifies that your Lowdefy app works correctly from the user's perspective. Instead of testing individual functions, e2e tests open a real browser, navigate through your pages, fill in forms, click buttons, and check that everything behaves as expected.
+
+The `@lowdefy/e2e-utils` package provides a Playwright-based testing toolkit built specifically for Lowdefy apps. It understands Lowdefy's block system, state management, and request lifecycle, so you can write expressive tests without worrying about implementation details.
+
+## What it provides
+
+- **Locator-first API** — an intuitive pattern: get the thing, then do something with it
+- **Request mocking** — control request responses with static YAML files or inline overrides
+- **Block helpers** — type-aware interactions that know how to fill a TextInput, click a Button, or select from a Selector
+- **User authentication** — set test users per browser context with cookie-based session injection
+- **Scaffold command** — `npx @lowdefy/e2e-utils` sets up everything you need in seconds
+
+## How it works
+
+When you run your tests, Playwright:
+
+1. Builds your Lowdefy app as a production build
+2. Starts a local server
+3. Opens a browser and runs your test code against the live app
+
+The e2e server build exposes internal state on `window.lowdefy`, so your tests can assert on page state, request responses, and validation status.
+
+## Prerequisites
+
+- **Node.js 22+**
+- A working Lowdefy app (your app must build successfully)
+- **Playwright** (installed automatically during setup)
+
+> E2e tests run against a production build of your app. If your app has build errors, the tests will not be able to start. Make sure <code>npx lowdefy build</code> succeeds before running tests.
+
+## Quick example
+
+Here is what a simple test looks like:
+
+```javascript
+import { test } from './fixtures.js';
+
+test('contact form submits successfully', async ({ ldf }) => {
+  await ldf.goto('/contact');
+
+  await ldf.block('name_input').do.fill('Jane Doe');
+  await ldf.block('email_input').do.fill('jane@example.com');
+  await ldf.block('submit_btn').do.click();
+
+  await ldf.request('submit_form').expect.toFinish();
+  await ldf.state('form_submitted').expect.toBe(true);
+  await ldf.url().expect.toBe('/thank-you');
+});
+```
+
+The `ldf` object is your main testing helper. It is provided automatically by the test fixtures and gives you access to blocks, requests, state, and URL assertions.

package/content/testing/e2e-mocking.md

@@ -0,0 +1,155 @@
+# Mocking Requests
+
+Some requests in your app may depend on external services that are unavailable in a test environment — for example, Atlas Search, third-party APIs, or services that require production credentials. Request mocking lets you control what these requests return, so your tests are fast, reliable, and independent of external systems.
+
+There are two ways to mock requests:
+
+- **Static mocks** — defined in `mocks.yaml`, applied to every test automatically
+- **Inline mocks** — defined per-test in your test code, for test-specific scenarios
+
+## Static mocks (mocks.yaml)
+
+The `mocks.yaml` file in your `e2e/` directory defines mocks that apply to all tests. This is useful for requests that should always be mocked in the test environment.
+
+```yaml
+requests:
+  - requestId: atlas_search
+    response:
+      - _id: doc-1
+        title: Search Result
+        score: 0.95
+
+  - requestId: fetch_config
+    response:
+      theme: dark
+      features:
+        - analytics
+        - notifications
+```
+
+### Page-specific mocks
+
+You can scope a mock to a specific page using `pageId`:
+
+```yaml
+requests:
+  - requestId: fetch_data
+    pageId: admin-dashboard
+    response: []
+```
+
+### Wildcard patterns
+
+Use `*` wildcards to match multiple request or page IDs:
+
+```yaml
+requests:
+  # Match any request starting with "fetch_"
+  - requestId: fetch_*
+    response: []
+
+  # Match fetch_* only on pages starting with "admin-"
+  - requestId: fetch_*
+    pageId: admin-*
+    response: []
+```
+
+### Error mocks
+
+You can simulate request errors:
+
+```yaml
+requests:
+  - requestId: atlas_search
+    error: Atlas Search is not available in the test environment
+```
+
+### API endpoint mocks
+
+You can also mock Lowdefy API endpoints:
+
+```yaml
+api:
+  - endpointId: external_webhook
+    method: POST
+    response:
+      status: ok
+      message: Webhook received
+```
+
+## Inline mocks (per-test)
+
+Use `ldf.mock.request()` and `ldf.mock.api()` to set up mocks for individual tests. Inline mocks override static mocks for the same request ID.
+
+### Mock a request response
+
+```javascript
+test('handles empty search results', async ({ ldf }) => {
+  await ldf.mock.request('search_products', {
+    response: [],
+  });
+
+  await ldf.goto('/search');
+  await ldf.block('search_input').do.fill('nonexistent');
+  await ldf.block('search_btn').do.click();
+
+  await ldf.request('search_products').expect.toFinish();
+  await ldf.block('no_results_alert').expect.visible();
+});
+```
+
+### Simulate an error
+
+```javascript
+test('shows error message when request fails', async ({ ldf }) => {
+  await ldf.mock.request('save_user', {
+    error: 'Database connection failed',
+  });
+
+  await ldf.goto('/profile');
+  await ldf.block('save_btn').do.click();
+
+  // Your app should handle the error gracefully
+});
+```
+
+### Mock an API endpoint
+
+```javascript
+await ldf.mock.api('external_webhook', {
+  method: 'POST',
+  response: { status: 'ok' },
+});
+```
+
+When you specify `method`, only that HTTP method is intercepted. Other methods pass through to the real server.
+
+## Capturing request payloads
+
+Mocked requests automatically capture the payload sent by your app. This is useful for asserting that the correct data was sent:
+
+```javascript
+test('search sends correct payload', async ({ ldf }) => {
+  await ldf.mock.request('search_products', { response: [] });
+
+  await ldf.goto('/search');
+  await ldf.block('search_input').do.fill('widget');
+  await ldf.block('search_btn').do.click();
+
+  const captured = ldf.mock.getCapturedRequest('search_products');
+  expect(captured.payload).toEqual(
+    expect.objectContaining({ query: 'widget' })
+  );
+});
+```
+
+Use `ldf.mock.clearCapturedRequests()` to clear captured payloads between assertions if needed.
+
+## Mock priority
+
+When both static and inline mocks exist for the same request:
+
+1. Static mocks from `mocks.yaml` are applied first (during test setup)
+2. Inline mocks override static mocks for the same request ID
+
+This means you can set sensible defaults in `mocks.yaml` and override them in specific tests.

package/content/testing/e2e-writing-tests.md

@@ -0,0 +1,214 @@
+# Writing Tests
+
+The `ldf` object is your main interface for testing Lowdefy apps. It is provided by the test fixtures and gives you a locator-first API — you get the thing you want to interact with, then perform actions or assertions on it.
+
+## Navigation
+
+Navigate to a page and wait for Lowdefy to be ready:
+
+```javascript
+await ldf.goto('/my-page');
+```
+
+If your test triggers a page navigation (for example, a Link action), you can wait for the new page:
+
+```javascript
+await ldf.block('next_btn').do.click();
+await ldf.waitForPage('/next-page');
+```
+
+You can also access the current page ID and the raw Playwright page object:
+
+```javascript
+const pageId = ldf.pageId;          // e.g. 'contact-form'
+const playwrightPage = ldf.page;    // for advanced Playwright usage
+```
+
+## Block interactions
+
+Use `ldf.block('blockId')` to get a block, then call methods on it.
+
+### Actions (`do`)
+
+The available `do` methods depend on the block type. Common examples:
+
+```javascript
+// TextInput - fill, clear
+await ldf.block('name_input').do.fill('John Doe');
+await ldf.block('name_input').do.clear();
+
+// Button - click
+await ldf.block('submit_btn').do.click();
+
+// Selector - select an option
+await ldf.block('category').do.select('Support');
+
+// NumberInput - fill with a number
+await ldf.block('quantity').do.fill('5');
+
+// TextArea - fill with text
+await ldf.block('comments').do.fill('This is a comment');
+```
+
+### Assertions (`expect`)
+
+Every block has these built-in assertion methods:
+
+```javascript
+await ldf.block('submit_btn').expect.visible();
+await ldf.block('submit_btn').expect.hidden();
+await ldf.block('submit_btn').expect.disabled();
+await ldf.block('submit_btn').expect.enabled();
+```
+
+Block types can also provide their own assertions:
+
+```javascript
+// TextInput - check value and placeholder
+await ldf.block('name_input').expect.value('John Doe');
+await ldf.block('name_input').expect.placeholder('Enter your name');
+
+// Button - check text
+await ldf.block('submit_btn').expect.text('Submit');
+```
+
+> The available <code>do</code> and <code>expect</code> methods depend on the block type. If you call a method that does not exist, you will get a clear error listing the available methods.
+
+### Raw locator access
+
+If you need to do something not covered by the block helpers, you can get the raw Playwright locator:
+
+```javascript
+const locator = ldf.block('my_block').locator();
+await locator.scrollIntoViewIfNeeded();
+await locator.screenshot({ path: 'block.png' });
+```
+
+## State
+
+Use `ldf.state('key')` to interact with page state.
+
+### Assert state values
+
+```javascript
+await ldf.state('form_submitted').expect.toBe(true);
+await ldf.state('selected_items').expect.toBe(['item1', 'item2']);
+```
+
+### Set state programmatically
+
+```javascript
+await ldf.state('search_query').do.set('widget');
+```
+
+### Read state values
+
+```javascript
+// Get a specific state value
+const name = await ldf.state('name_input').value();
+
+// Get the entire page state
+const allState = await ldf.state().value();
+```
+
+You can use dot notation for nested state:
+
+```javascript
+await ldf.state('form.email').expect.toBe('jane@example.com');
+```
+
+## Requests
+
+Use `ldf.request('requestId')` to assert on request state and responses.
+
+### Wait for a request to complete
+
+```javascript
+await ldf.request('fetch_users').expect.toFinish();
+```
+
+### Assert the response
+
+```javascript
+await ldf.request('fetch_users').expect.toHaveResponse([
+  { id: 1, name: 'Alice' },
+  { id: 2, name: 'Bob' },
+]);
+```
+
+`toHaveResponse` uses an exact match — the actual response must be identical to the expected value.
+
+### Assert the payload
+
+```javascript
+await ldf.request('search').expect.toHavePayload({ query: 'widget' });
+```
+
+`toHavePayload` uses a partial match — the actual payload only needs to contain the keys you specify. It can have additional keys.
+
+### Read the raw response
+
+```javascript
+const data = await ldf.request('fetch_users').response();
+```
+
+## URL
+
+Use `ldf.url()` and `ldf.urlQuery('key')` for URL assertions.
+
+### Assert the current URL
+
+```javascript
+await ldf.url().expect.toBe('/dashboard');
+await ldf.url().expect.toMatch(/dashboard/);
+```
+
+### Work with query parameters
+
+```javascript
+// Assert a query parameter
+await ldf.urlQuery('tab').expect.toBe('settings');
+
+// Set a query parameter
+await ldf.urlQuery('page').do.set('2');
+
+// Read a query parameter
+const tab = ldf.urlQuery('tab').value();
+```
+
+## Validation
+
+You can assert on block validation status using the built-in validation methods:
+
+```javascript
+// Trigger validation by clicking submit
+await ldf.block('submit_btn').do.click();
+
+// Check that a block has a validation error
+await ldf.block('email_input').expect.validationError();
+
+// Check for a specific error message
+await ldf.block('email_input').expect.validationError({
+  message: 'Please enter a valid email address',
+});
+
+// Check for warnings and success
+await ldf.block('age_input').expect.validationWarning();
+await ldf.block('name_input').expect.validationSuccess();
+```
+
+## Timeouts
+
+Assertion methods accept an optional `{ timeout }` parameter (in milliseconds):
+
+```javascript
+// Wait up to 60 seconds for a slow request
+await ldf.request('generate_report').expect.toFinish({ timeout: 60000 });
+
+// Wait up to 10 seconds for state to update
+await ldf.state('processed').expect.toBe(true, { timeout: 10000 });
+```
+
+Default timeouts:
+- Request assertions: 30 seconds
+- State, URL, and validation assertions: 5 seconds