functions/partials/pageTools.mjsjavascript
/* global MutationObserver -- the functions given to page.evaluate run in the browser, where it exists */
/**
* Small helpers for scripts that drive a real page with Playwright (see launchBrowser and serveStatic): collect what
* went wrong on the page, click a control by its label, and count how much of the page changes.
*/
/**
* Collect everything that goes wrong on a page from now on: uncaught errors, console errors, requests that fail, and
* responses with an HTTP error status. Read the returned array whenever you like; it keeps filling while the page runs.
* @memberOf module:partials
* @param {Object} page - A Playwright page.
* @param {Object} [options]
* @param {Array<RegExp>} [options.ignore=[]] - Messages or URLs to leave out, such as an analytics script that is
* blocked when testing locally.
* @returns {Array<string>} The problems, each as "kind: message", in the order they happened.
*/
export const watchPage = (page, { ignore = [] } = {}) => {
const problems = []
const add = (kind, text) => {
if (!ignore.some(pattern => pattern.test(text))) {
problems.push(`${kind}: ${text}`)
}
}
page.on('pageerror', error => add('pageerror', error.message))
page.on('console', message => {
if (message.type() === 'error') {
// The browser's own "Failed to load resource" message doesn't say which one; its location does
const where = message.location()?.url
const text = message.text()
add('console', /^Failed to load resource/.test(text) && where ? `${text} (${where})` : text)
}
})
page.on('requestfailed', request => add('requestfailed', request.url()))
page.on('response', response => {
if (response.status() >= 400) {
add(`HTTP ${response.status()}`, response.url())
}
})
return problems
}
/**
* Find the visible control with this label, in the page: buttons, and inputs of type button or submit, by their text or
* value with whitespace collapsed (a label written over several lines matches). The exact label first, otherwise the
* first that contains it (case-sensitive). With a mark, the control found gets that data attribute so Playwright can
* click it; with list, the visible labels are returned instead.
* @private
*/
const findControl = ({ label, mark, list }) => {
const visible = element => element.offsetParent !== null || element.getClientRects().length > 0
const controls = Array.from(document.querySelectorAll('button, input[type=button], input[type=submit]')).filter(visible)
const name = element => (element.tagName === 'INPUT' ? element.value : element.textContent).replace(/\s+/g, ' ').trim()
if (list) {
return controls.map(name)
}
const wanted = label.replace(/\s+/g, ' ').trim()
const control = controls.find(element => name(element) === wanted) ?? controls.find(element => name(element).includes(wanted))
if (!control) {
return false
}
if (mark) {
control.setAttribute(mark, '')
} else {
control.click()
}
return true
}
/**
* Click the visible button (or input of type button/submit) with this label: its exact text or value, otherwise the
* first whose text or value contains it (whitespace collapsed, case-sensitive). Both ways of clicking find the control
* the same way. Fails straight away, naming the controls that are there, instead of waiting for a timeout.
* @memberOf module:partials
* @param {Object} page - A Playwright page.
* @param {string} label - The text on the control.
* @param {Object} [options]
* @param {boolean} [options.inPage=false] - Find and click it in one step inside the page, rather than with
* Playwright's click (which waits for the element to be stable, and moves the mouse). Use it for a page that
* replaces its elements while you click (one that re-renders on every update), where Playwright's click can find an
* element that is gone a moment later ("element was detached").
* @returns {Promise<void>}
* @throws {Error} When no visible control has that label.
*/
export const clickLabel = async (page, label, { inPage = false } = {}) => {
const mark = inPage ? null : `data-page-tools-${Math.random().toString(36).slice(2)}`
if (await page.evaluate(findControl, { label, mark, list: false })) {
if (mark) {
const control = page.locator(`[${mark}]`)
await control.click()
await control.evaluate((element, name) => element.removeAttribute(name), mark).catch(() => {})
}
return
}
const present = await page.evaluate(findControl, { label, list: true })
throw new Error(`No visible control labelled "${label}". Visible: ${present.length ? present.map(name => `"${name}"`).join(', ') : 'none'}`)
}
/**
* Start counting how much of the page changes: elements added and removed (every element of an added or removed
* subtree counts, not just its top), attribute writes, and text changes (a text node's value changed, or a text node
* added or removed). Useful to measure what one action costs, or to check that an update only touched what it should.
* Counting stops when the page navigates or reloads; read() then fails saying so.
* @memberOf module:partials
* @param {Object} page - A Playwright page, already loaded.
* @param {string} [selector='body'] - The element to watch, with everything inside it.
* @returns {Promise<{read: function(): Promise<{added: number, removed: number, attributes: number, text: number}>}>}
* read() returns the counts since the last read (or since counting started) and starts the next count from zero.
* @throws {Error} When no element matches the selector.
*/
export const trackMutations = async (page, selector = 'body') => {
const key = `__pageToolsMutations${Math.random().toString(36).slice(2)}`
await page.evaluate(({ key, selector }) => {
const counts = { added: 0, removed: 0, attributes: 0, text: 0 }
const target = document.querySelector(selector)
if (!target) {
throw new Error(`No element matches "${selector}"`)
}
// An element counts with every element inside it; a text or comment node counts as a text change
const tally = (node, name) => {
if (node.nodeType === 1) {
counts[name] += 1 + node.getElementsByTagName('*').length
} else {
counts.text++
}
}
const count = records => records.forEach(record => {
if (record.type === 'childList') {
record.addedNodes.forEach(node => tally(node, 'added'))
record.removedNodes.forEach(node => tally(node, 'removed'))
} else if (record.type === 'attributes') {
counts.attributes++
} else {
counts.text++
}
})
const observer = new MutationObserver(count)
observer.observe(target, { subtree: true, childList: true, attributes: true, characterData: true })
window[key] = () => {
count(observer.takeRecords())
const result = { ...counts }
Object.keys(counts).forEach(name => { counts[name] = 0 })
return result
}
}, { key, selector })
return {
read: () => page.evaluate(key => {
if (typeof window[key] !== 'function') {
throw new Error('trackMutations stopped counting: the page navigated or reloaded; start it again')
}
return window[key]()
}, key)
}
}