Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | /**
* Page smoke helpers for blong portal applications.
*
* `model.ts` covers what a model page *does* — browse, create, edit. This covers
* whether a realm's pages open at all: under a real session, with a real gateway
* behind them, and a screenshot to prove it. Both are the same kind of helper, so
* a realm's UI spec is a list of pages instead of a hand-rolled test per page.
*
* Usage:
* ```ts
* import {test, expect} from '@feasibleone/blong-browser/playwright';
* import {openPages} from '@feasibleone/blong-browser/playwright/pages';
*
* openPages(test, expect, {
* methods: ['blong.flow.browse', {method: 'blong.search.browse', waitForTableData: false}],
* screenshot: method => `${method.split('.')[1]}.png`,
* });
* ```
*
* A page that renders an error panel, that never leaves its loading state, or
* whose realm was never mounted looks exactly like a page with no data — which is
* why this waits for the page's table before capturing, and why the `portal`
* fixture fails a test outright when the browser throws while the page loads.
*/
import type {Expect, Page, Request, Response} from '@playwright/test';
import type {Portal} from '../playwright.js';
import {captureDocs} from './docs.js';
import type {ITestFn} from './model.js';
/** How long a debounced search has to turn into a read before it is judged local. */
const SEARCH_PROBE_MS = 600;
/** A read the search did issue is given this long to be answered. */
const FILTERED_READ_MS = 15_000;
/** Stride of the poll that waits out a debounce. */
const POLL_MS = 50;
/** One page: its method, or the method plus the parts that differ for it. */
export interface IOpenPage {
/** The portal menu method — a semantic triple, e.g. `blong.flow.browse`. */
method: string;
/** Baseline name for this page, overriding the default. */
screenshot?: string;
/** Wait for this page's table. Defaults to the spec-wide `waitForTableData`. */
waitForTableData?: boolean;
/**
* Text typed into the page's filter (`browse-search`) before capturing.
*
* A page whose content grows with every run — a change stream, a list of what
* has been observed so far — is only stable once its rows are pinned to a
* stable subset. The same idea as `browseModel`'s `searchText`.
*/
searchText?: string;
/**
* Locators masked in the capture, for a cell whose value cannot repeat: an id
* minted per execution, a wall clock. Masking is honest here and pinning is
* not — the cell shows something, it just cannot be the same something twice.
*/
mask?: readonly string[];
/**
* Capture this element instead of the whole page.
*
* Filtering pins *which* rows a table shows; it does not pin *how many*, and a
* stream that grows during a run (a change digest) therefore cannot be captured
* whole. Capturing the first row is exact — the row is the newest one of its
* kind, and its content is what the page is for.
*/
region?: string;
/** Documentation image for this page, relative to the docs tree. Overrides {@link IOpenPagesOptions.docs}. */
docs?: string;
}
export interface IOpenPagesOptions {
/** The pages to open, in order. A bare string takes every default. */
methods: readonly (string | IOpenPage)[];
/** Baseline name for a method. Defaults to the triple with dots replaced by dashes. */
screenshot?: (method: string) => string;
/** Wait for each page's table to render. Defaults to `true`. */
waitForTableData?: boolean;
/** Filter text typed into every page. Defaults to none. */
searchText?: string;
/** Prefix every baseline, to keep two specs off the same screenshot files. */
baselinePrefix?: string;
/**
* Also write a documentation image for a page, named relative to the docs tree —
* `patterns/img/access-role-browse.png`, say. The page is captured with the same
* `searchText`, `mask` and `region` the baseline uses, so the picture is pinned by the
* settings a reader can see rather than by a second set that could drift from them.
*
* The image is written only when `BLONG_CAPTURE_DOCS=1` (see
* {@link captureDocs}), so a CI run checks the page without overwriting a committed
* picture.
*/
docs?: (method: string) => string | undefined;
/**
* Write only the documentation images: skip the baseline comparison entirely.
*
* For a spec whose pages exist to be photographed rather than to be guarded — a realm
* showing a feature the docs describe, where a new baseline would be a snapshot nobody
* asked to maintain. Requires {@link IOpenPagesOptions.docs}.
*/
docsOnly?: boolean;
/**
* How many pages one test opens (default 1).
*
* A test's largest cost is its boot: a fresh browser context fetches the app, draws the
* login screen, signs in and waits for the composed portal before the first click — ten
* seconds on a CI runner, and every page-open test pays it again. Opening six pages in
* one test pays it once and visits six pages, which is what took blong-sport's 46 page
* tests to 630 s (`@@D-748`).
*
* Each page is still captured under its own name, and the tab it opened is closed again
* before the next one: a capture with three tabs behind it is a different picture from
* one with a single tab, so grouping must not move a baseline. A failure names the page
* it was on in the error, not just the group, and the group is a *slice of the list* —
* so a failure costs at most `groupSize - 1` pages of evidence, never the whole spec.
*/
groupSize?: number;
}
/**
* Fill the browse filter and wait for the table to show the filtered rows.
*
* Typing into the box is not filtering: the box is debounced (350 ms), and only
* then does the table apply the term — either by asking the server again or by
* filtering the rows it already has. Which of the two happens decides what has to be
* waited for, and a capture taken too early is the bug this exists to prevent: the
* picture showed the *unfiltered* rows with the term typed into the box (`F-603`).
*
* The page's own first read must have settled before this is called, or that read is
* the one this would mistake for the search's. After the fill the two are told apart
* by counting reads: the search's own read arrives behind the debounce, and the answer
* it gets is what the capture waits for. A page that filters the rows it holds issues
* nothing, and the debounce is all there is to wait out.
*
* Predicting the form from the page's method name does not work, and guessing it
* costs a full wait when wrong: a fixed 15 s response wait turned three of a realm's
* client-filtered captures into timeouts on CI, where the whole test is budgeted at
* 20 s.
*/
async function fillBrowseSearch(page: Page, searchText: string, findPath: string): Promise<void> {
const isRead = (url: string, method: string) => method === 'POST' && url.includes(findPath);
let reads = 0;
let answers = 0;
const onRequest = (request: Request) => {
if (isRead(request.url(), request.method())) reads++;
};
const onResponse = (response: Response) => {
if (isRead(response.url(), response.request().method())) answers++;
};
page.on('request', onRequest);
page.on('response', onResponse);
try {
const readsBefore = reads;
const answersBefore = answers;
await page.getByTestId('browse-search').fill(searchText);
// The probe outlasts the debounce, so a page that filters the rows it holds
// has committed by the time this gives up: nothing more to wait for.
if (!(await settles(() => reads > readsBefore, page, SEARCH_PROBE_MS))) return;
// A read nobody answered is a page still loading; the caller's table wait
// reports that better than this helper could.
await settles(() => answers > answersBefore, page, FILTERED_READ_MS);
} finally {
page.off('request', onRequest);
page.off('response', onResponse);
}
}
/** Poll `until` in short steps, so a debounce is waited out rather than guessed at. */
async function settles(until: () => boolean, page: Page, timeout: number): Promise<boolean> {
const deadline = Date.now() + timeout;
while (!until()) {
if (Date.now() > deadline) return false;
await page.waitForTimeout(POLL_MS);
}
return true;
}
/**
* Register one test per page. Each opens the page from the portal menu, waits for
* its data and captures it, so a realm states its pages as a list.
*
* `waitForTableData: false` is for a page that legitimately has no table — a
* search page before anything is typed, say — where the wait could only time out.
*/
export function openPages(
test: ITestFn,
expect: Expect,
{
methods,
screenshot,
waitForTableData = true,
searchText: defaultSearchText,
baselinePrefix,
docs,
docsOnly = false,
groupSize = 1,
}: IOpenPagesOptions,
): void {
if (docsOnly && docs === undefined) {
throw new Error('openPages: docsOnly needs a docs() name for the images it writes');
}
const pages: IOpenPage[] = methods.map(entry =>
typeof entry === 'string' ? {method: entry} : entry,
);
const groups: IOpenPage[][] = [];
for (let index = 0; index < pages.length; index += Math.max(1, groupSize)) {
groups.push(pages.slice(index, index + Math.max(1, groupSize)));
}
for (const group of groups) {
const first = group[0] as IOpenPage;
const name = `${docsOnly ? 'document' : 'open'} ${first.method}${group.length > 1 ? ` +${group.length - 1}` : ''}`;
test(name, async ({portal}) => {
for (const page of group) {
await openOne(portal, page);
if (group.length > 1) {
// Back to the empty portal, so the next capture is the picture its
// baseline was taken in — one tab and nothing behind it.
await portal.tabsCloseAll();
}
}
});
}
async function openOne(portal: Portal, page: IOpenPage): Promise<void> {
const baseline =
page.screenshot ??
screenshot?.(page.method) ??
`${page.method.replace(/\./g, '-')}.png`;
await portal.menuClick(page.method);
const searchText = page.searchText ?? defaultSearchText;
const wantsData = page.waitForTableData ?? waitForTableData;
if (searchText !== undefined) {
// The page's own first read has to settle first: a read still in
// flight would be the one the search wait mistakes for its own.
// `@@F-603`
if (wantsData) await portal.waitForTableData();
const [subject, object] = page.method.split('.');
await fillBrowseSearch(portal.page, searchText, `/rpc/${subject}/${object}/find`);
}
if (wantsData) await portal.waitForTableData();
const target =
page.region === undefined ? portal.page : portal.page.locator(page.region).first();
if (!docsOnly) {
await expect(target).toHaveScreenshot(
baselinePrefix === undefined ? baseline : `${baselinePrefix}-${baseline}`,
page.mask === undefined
? {}
: {mask: page.mask.map(selector => portal.page.locator(selector))},
);
}
const docsName = page.docs ?? docs?.(page.method);
if (docsName !== undefined) {
await captureDocs(portal, {
name: docsName,
...(page.region === undefined ? {} : {region: page.region}),
...(page.mask === undefined ? {} : {mask: page.mask}),
});
}
}
}
|