How to run real end-to-end UI tests against a deployed Forge app (2026)

Key takeaways

• Forge Custom UI renders inside a sandboxed iframe, so every Playwright locator has to be scoped through the frame.
• A REST API token can't open a browser session; a persistent Chrome profile keeps Atlassian's 2FA from re-challenging every run.
• Config video/trace capture doesn't apply to a context you launch yourself — you record it in the fixture instead.
• One on-disk profile can't be shared by parallel workers, so the suite runs on a single worker.

Every Forge developer I know has shipped an app whose unit tests were green and which still fell over the first time a real user opened it in Jira. The resolver was fine. What broke was everything around it: the app renders inside a sandboxed iframe, on a page you reach through three menu clicks, behind a login that wants a second factor. None of that gets exercised by a Node test that imports your resolver and calls it directly. So you find out it's broken when someone tells you it's broken.

I got tired of that and built a harness that opens the real product in a real browser, navigates to the deployed app, and asserts on what actually renders. It drives five of our Forge apps across Jira and Confluence now, and it has caught fifteen bugs that every offline test waved through. Here's how it works, including the two things that cost me an afternoon each so you can skip them.

Prerequisites — a Forge app deployed to a dev environment you can log into, Node 18+, and Playwright (npm i -D @playwright/test && npx playwright install chromium). You'll need the app's UUID (from your manifest's app.id, dropping the ari:cloud:ecosystem::app/ prefix, or from the Developer Console) and the environment id (from the Developer Console, or the forge deploy --verbose output — forge environments list shows environment names, not the id you need). This is written for Custom UI. Modern UI Kit (@forge/react) also renders through a hosted iframe, so most of it applies — but dump the frames first (there's a snippet below) and confirm where your app actually lives before you assume anything.

Why can't I just point Playwright at the app?

Auth is the first wall, and the token you already have is useless against it. A Forge REST API token talks to the REST API; it can't mint a browser session, so there's no header that makes you "logged in". You have to log in through the browser for real. And the moment you try to do that headlessly and replay a saved storageState, Atlassian treats the run as a brand-new device and asks for a 2FA code your script can't produce.

The token rabbit hole. I spent a while trying to make a headless login stick: export storageState, replay it, get challenged for a code, repeat. The fix wasn't a smarter token. It was to stop throwing away the login between runs — keep the whole browser profile on disk and Atlassian stops treating you as a stranger.

The second wall is the iframe. Forge Custom UI renders your React app inside an iframe for isolation, which is documented and deliberate. Your page.getByRole(...) calls run against the host page, and the host page doesn't contain your app, so they match nothing while you stare at a button you can plainly see and wonder why it isn't found. Everything for your app's UI has to be scoped through the frame.

A persistent profile that captures its own evidence

Instead of a fresh context per run, launch a persistent context pointed at a directory you keep around, and wrap it in a fixture. Log in by hand the first time; every run after reuses the cookies and the remembered-device token Atlassian stored in that profile, so the second factor stays quiet.

The fixture is also where you turn on video and tracing, and this is the part that bit me: Playwright's use: { video, trace } config only applies to the built-in page/context fixtures. A context you launch yourself ignores it completely. So you record evidence in the launch, or you get none.

**tests/fixtures.ts**

import { test as base, chromium, type BrowserContext } from "@playwright/test";
import path from "node:path";

// Gitignore this — it holds your session cookies and the remembered-device token.
const PROFILE_DIR = path.resolve(".auth/profile");

export const test = base.extend<{ site: BrowserContext }>({
  site: async ({}, use, testInfo) => {
    // headless:false is load-bearing. A headless profile trips the "new device" 2FA check.
    // recordVideo lives here because config `use: { video }` never reaches a context you launch.
    const ctx = await chromium.launchPersistentContext(PROFILE_DIR, {
      headless: false,
      viewport: { width: 1440, height: 900 },
      recordVideo: { dir: testInfo.outputDir },
    });
    await ctx.tracing.start({ screenshots: true, snapshots: true });
    try {
      await use(ctx);
    } finally {
      // Runs even when an assertion throws, so the profile lock is always released.
      // pages()[0] is the bootstrap about:blank a persistent context opens with, so
      // screenshot the LAST page — the one the test actually drove.
      if (testInfo.status !== testInfo.expectedStatus) {
        await ctx.pages().at(-1)?.screenshot({ path: path.join(testInfo.outputDir, "failure.png") });
      }
      await ctx.tracing.stop({ path: path.join(testInfo.outputDir, "trace.zip") });
      await ctx.close();
    }
  },
});

export { expect } from "@playwright/test";

1. Warm the profile once a throwaway script that launches the same PROFILE_DIR headed, opens your site, and sits on page.pause() while you complete SSO and the 2FA prompt by hand.
2. Reuse it everywhere every spec imports this fixture, so it's already authenticated and already recording.
3. Fail fast when it expires the session idles out after weeks; if a run lands on id.atlassian.com, stop and re-warm the profile instead of retrying blindly.

Deep-link straight to the app

Don't click through the product nav to reach your app; it's slow and it breaks. Forge app pages have stable deep links built from the app UUID and the environment id. Use the bare app UUID, not the full ARI. One asymmetry to know: a Confluence global page carries the module's route in the path, while a Jira global page doesn't.

**tests/deeplink.ts**

const SITE = process.env.SITE_URL!;      // https://your-dev.atlassian.net
const APP = process.env.FORGE_APP_ID!;   // bare UUID from manifest app.id
const ENV = process.env.FORGE_ENV_ID!;   // env UUID from the Developer Console / `forge deploy --verbose`
const ROUTE = process.env.FORGE_ROUTE!;  // the `route` on your confluence:globalPage module

// jira:globalPage — no route in the path
export const jiraGlobalPage = `${SITE}/jira/apps/${APP}/${ENV}`;
// confluence:globalPage — Confluence needs the module's route in the path
export const confluenceGlobalPage = `${SITE}/wiki/apps/${APP}/${ENV}/${ROUTE}`;

Issue panels and macros are the exception: their parameters get stripped, so they aren't deep-linkable. You reach those by driving the host page that contains them rather than by URL.

Drive the iframe

Now the whole pattern. Go to the deep link, grab the Custom UI frame, wait for the app's root to mount, then assert on the app like any page, just scoped to the frame.

**tests/dashboard.spec.ts**

import { test, expect } from "./fixtures";
import { jiraGlobalPage } from "./deeplink";

test("the dashboard renders and loads its data", async ({ site }) => {
  const page = await site.newPage();
  await page.goto(jiraGlobalPage);

  // Custom UI lives in one iframe; your app mounts into #root inside it.
  const app = page.frameLocator('iframe[data-testid="hosted-resources-iframe"]');
  await expect(app.locator("#root")).toBeVisible();

  // From here it's ordinary Playwright, scoped to `app` instead of `page`.
  await expect(app.getByRole("heading", { name: "Portfolio" })).toBeVisible();
  await expect(app.getByText("No data").first()).toBeHidden();
});

The one caveat about that selector. data-testid="hosted-resources-iframe" is an internal Atlassian attribute, not a documented contract. It's held for me across Jira and Confluence through 2026, but if a run suddenly can't find the frame, don't trust me — dump the page's frames and grab whichever one hosts your #root:

for (const f of page.frames()) console.log(f.name(), f.url());

The config, and the one line that scales it wrong

Two things earn a mention. Retries: live UI carries real network latency, so a couple in CI is reasonable. Workers: this is the one that will bite you. A single on-disk profile can't be opened by two Chromium processes at once — the directory is locked — so the whole suite has to run on one worker. Playwright parallelizes by default, and the first time a second worker tries to launch the same profile it just dies.

**playwright.config.ts**

import { defineConfig } from "@playwright/test";

export default defineConfig({
  // One shared profile → one worker. Chromium locks the user-data-dir; parallel workers can't share it.
  fullyParallel: false,
  workers: 1,
  retries: process.env.CI ? 2 : 0,
});

If a single worker is too slow once you have real coverage, the way up is to copy the warm profile into a per-worker temp directory at startup so each worker gets its own lockable copy. I ran on one worker far longer than I expected to before that mattered.

When one app becomes several

A single app is one spec file, and honestly you can just watch it yourself. The math changes when you're maintaining a handful of them, each with its own transitions and release cadence, and "did that last change break anything in the real product" stops being a question you can answer by hand.

Live testing earns its keep on the static checks too, not just the UI: forge lint cannot see calls made through a request helper, so an app can pass lint, pass deploy, pass install and still 401 on its first write. Only something that calls the real API catches that.

This is how we keep CogniRunner — our AI-backed Jira workflow validator, full disclosure it's one of ours — green across releases. Every rule type it ships gets driven through the real transition UI on a live site, and a failing run hands back the video plus a written note of what broke instead of a bare red X. If you want to see the kind of app this is built for, it's on the Atlassian Marketplace. The technique is the same whether the app is ours or yours.

Key takeaways

• The persistent-profile trick is the whole ballgame. Everything after it is normal Playwright.
• Scope every locator through the frame. Custom UI is a sandboxed iframe, and the host page has none of your app.
• Config use: { video, trace } doesn't reach a context you launch yourself — record it in the fixture, or you'll ship a suite that captures nothing.

Next steps — if you're newer to the platform, the LLM-powered Forge app tutorial gives you an app worth testing this way, and Dark Mode Done Right in Forge Custom UI pairs well if you want the styling to survive both product themes while you're in there.

The same harness drives LeanZero Management, and its release post covers the scheduling engine those live tests exercise, including the two-engine parity problem that made testing against a real deployment necessary.

That parity problem now has its own write-up: two scheduling engines, one schedule walks through why the two engines carry opposite off-by-one conventions, and the fixed-point harness that keeps the preview honest about what Apply will write.

I don't work for Atlassian, so treat the internal selector as "worked for me" rather than gospel. The shape of this holds regardless of which attribute names the platform uses this month. What's the bug a live test caught for you that every offline test let through?