e2e-testing

Source excerpt starting at line 1.

1# E2E Test Helper Functions2 3All helpers are located in `src/frontend/tests/utils/`. Import them by name.4 5## Bootstrap & Setup6 7### `awaitBootstrapTest(page, options?)`8 9**Call this at the start of EVERY test.** Waits for the app to fully load and optionally opens the new project modal.10 11```typescript12import { awaitBootstrapTest } from "../../utils/await-bootstrap-test";13 14// Default: waits for load + opens new project modal15await awaitBootstrapTest(page);16 17// Skip opening modal (for tests that start on an existing page)18await awaitBootstrapTest(page, { skipModal: true });19```20 21Why: Without this, tests race against the app's initialization. Components may not be rendered, stores may not be hydrated, and API calls may not be complete. Every flaky "element not found" failure is likely a missing `awaitBootstrapTest`.22 23### `initialGPTsetup(page, options?)`24 25Full OpenAI setup pipeline. Calls 6 steps in order:261. `adjustScreenView` — fit view + zoom out272. `updateOldComponents` — update any outdated components283. `selectGptModel` — select gpt-4o-mini for all Language Model nodes294. `addOpenAiInputKey` — fill OPENAI_API_KEY in all openai_api_key fields305. `adjustScreenView` — fit again (components may have moved)316. `unselectNodes` — click empty canvas to deselect32 33```typescript34// All steps35await initialGPTsetup(page);36 37// Skip specific steps38await initialGPTsetup(page, {39  skipAdjustScreenView: true,40  skipUpdateOldComponents: true,41  skipSelectGptModel: true,42});43```44 45Why: Many tests need a working OpenAI-connected flow. This helper standardizes the setup so test authors don't reinvent it. The order matters — updating components before selecting models prevents stale model dropdowns.46 47## Canvas Controls48 49### `adjustScreenView(page, options?)`50 51Clicks "fit view" then zooms out. Ensures all nodes are visible and interactable.52 53```typescript54await adjustScreenView(page);                          // Default: fit + 1 zoom out55await adjustScreenView(page, { numberOfZoomOut: 3 });  // Fit + 3 zoom outs56```57 58Why: After adding components, some may be off-screen or overlapping. Fit view centers them; zoom out ensures click targets are large enough for Playwright to hit reliably.59 60### `zoomOut(page, times)`61 62Zooms out the canvas a specific number of times.63 64```typescript65await zoomOut(page, 5);66```67 68### `unselectNodes(page)`69 70Clicks the empty canvas area at position (0, 0) to deselect all nodes.71 72```typescript73await unselectNodes(page);74```75 76Why: Selected nodes show selection UI (toolbars, handles) that can overlay other elements. Deselecting before interacting with other elements prevents click interception.77 78## Component Setup79 80### `selectGptModel(page)`81 82Finds all Language Model nodes and selects `gpt-4o-mini` in their model dropdown.83 84Why: Tests that require LLM execution need a specific model. Using `gpt-4o-mini` keeps costs low and responses fast.85 86### `addOpenAiInputKey(page)`87 88Finds all fields with `data-testid="popover-anchor-input-openai_api_key"` and fills them with `process.env.OPENAI_API_KEY`.89 90**Warning**: Only works when the field renders as an `<input>`. If a global variable is selected (badge mode), this helper won't find the field. Check the template's `load_from_db` setting.91 92### `updateOldComponents(page)`93 94If the canvas shows an "Update all" button (outdated components), clicks it and waits for update to complete.95 96Why: Saved flows from older versions may have outdated component definitions. Updating them ensures the test runs against current component behavior, not stale cached versions.97 98## Inspection Panel99 100### `enableInspectPanel(page)`101 102Opens the canvas controls dropdown and toggles the inspection panel ON.103 104**MUST be called BEFORE any interaction with `edit-fields-button`.** Without it, the inspection panel is hidden and `edit-fields-button` does not exist in the DOM.105 106```typescript107await enableInspectPanel(page);108await page.getByTestId("title-OpenAI").click();       // Select a node109await page.getByTestId("edit-fields-button").click();  // Now visible110```111 112### `disableInspectPanel(page)`113 114Toggles the inspection panel OFF. Use for cleanup or when testing canvas-only behavior.115 116## Flow Management117 118### `renameFlow(page, options)`119 120Renames the current flow in the workspace.121 122```typescript123await renameFlow(page, { flowName: "My Test Flow" });124```125 126### `uploadFile(page, filename)`127 128Uploads a file from the `tests/assets/` directory.129 130```typescript131await uploadFile(page, "test-document.pdf");132```133 134## Event Delivery Modes135 136### `withEventDeliveryModes(title, config, testFn, options?)`137 138Wraps a test function to run it 3 times: once for each event delivery mode (streaming, polling, direct). Each mode is configured by intercepting the `/api/v1/config` route.139 140```typescript141import { withEventDeliveryModes } from "../../utils/withEventDeliveryModes";142 143withEventDeliveryModes(144  "Document Q&A should process and respond",145  { tag: ["@release", "@starter-projects"] },146  async ({ page }) => {147    // Test body — runs 3 times with different delivery modes148    await page.getByTestId("input-chat-playground").fill("What is this about?");149    await page.keyboard.press("Enter");150    await expect(page.getByTestId("div-chat-message")).toBeVisible({ timeout: 60000 });151  },152  { timeout: 10000 },  // Optional delay between mode switches153);154```155 156Why: Langflow supports 3 event delivery modes. A bug that only appears in polling mode would be missed if tests only run in streaming mode. This helper ensures all modes are covered without writing 3x the tests.157 158## Advanced Patterns159 160### `openAdvancedOptions(page)` (LEGACY)161 162Opens the old edit modal for component configuration. **Deprecated** — use `enableInspectPanel` + `edit-fields-button` for new tests.163 164### `closeAdvancedOptions(page)` (LEGACY)165 166Closes the old edit modal. **Deprecated**.167 168## Creating New Helpers169 170When to create a new helper:171- The same 5+ lines of setup appear in 3+ test files (DRY)172- The pattern involves complex waits or retries that are easy to get wrong173- The helper encapsulates Langflow-specific knowledge (e.g., global variable badge behavior)174 175When NOT to create a helper:176- For a single test's setup (keep it inline)177- For generic Playwright operations (use Playwright API directly)178- For assertions (assertions should be explicit in the test, not hidden in helpers)179 180Place new helpers in `src/frontend/tests/utils/` with kebab-case naming: `my-new-helper.ts`.181