diff --git a/packages/govuk-frontend/src/govuk/components/button/button.puppeteer.test.js b/packages/govuk-frontend/src/govuk/components/button/button.puppeteer.test.js index e6b3bf6590..5ce59b3f15 100644 --- a/packages/govuk-frontend/src/govuk/components/button/button.puppeteer.test.js +++ b/packages/govuk-frontend/src/govuk/components/button/button.puppeteer.test.js @@ -43,8 +43,8 @@ describe('/components/button', () => { /** * Sets the number of times a button was clicked * - * @param {import('puppeteer').ElementHandle} $button - Puppeteer button element - * @returns {Promise>} Puppeteer button element + * @param {ElementHandle} $button - Puppeteer button element + * @returns {Promise>} Puppeteer button element */ async function setButtonTracking($button) { const counts = { @@ -80,7 +80,7 @@ describe('/components/button', () => { /** * Gets the number of times the button was clicked * - * @param {import('puppeteer').ElementHandle} $button - Puppeteer button element + * @param {ElementHandle} $button - Puppeteer button element * @returns {Promise<{ click: number; debounce: number; }>} Number of times the button was clicked */ function getButtonTracking($button) { @@ -91,7 +91,7 @@ describe('/components/button', () => { } describe('not enabled', () => { - /** @type {import('puppeteer').ElementHandle} */ + /** @type {ElementHandle} */ let $button beforeEach(async () => { @@ -111,7 +111,7 @@ describe('/components/button', () => { }) describe('using data-attributes', () => { - /** @type {import('puppeteer').ElementHandle} */ + /** @type {ElementHandle} */ let $button beforeEach(async () => { @@ -165,7 +165,7 @@ describe('/components/button', () => { }) describe('using JavaScript configuration', () => { - /** @type {import('puppeteer').ElementHandle} */ + /** @type {ElementHandle} */ let $button beforeEach(async () => { @@ -224,7 +224,7 @@ describe('/components/button', () => { }) describe('using JavaScript configuration, but cancelled by data-attributes', () => { - /** @type {import('puppeteer').ElementHandle} */ + /** @type {ElementHandle} */ let $button beforeEach(async () => { @@ -248,7 +248,7 @@ describe('/components/button', () => { }) describe('using `initAll`', () => { - /** @type {import('puppeteer').ElementHandle} */ + /** @type {ElementHandle} */ let $button beforeEach(async () => { @@ -363,3 +363,7 @@ describe('/components/button', () => { }) }) }) + +/** + * @import { ElementHandle } from 'puppeteer' + */ diff --git a/shared/helpers/puppeteer.js b/shared/helpers/puppeteer.js index 8dfad96b06..1aa8e04c1c 100644 --- a/shared/helpers/puppeteer.js +++ b/shared/helpers/puppeteer.js @@ -11,9 +11,9 @@ const slug = require('slug') /** * Axe Puppeteer reporter * - * @param {import('puppeteer').Page} page - Puppeteer page object - * @param {import('axe-core').RuleObject} [overrides] - Axe rule overrides - * @returns {Promise} Axe Puppeteer instance + * @param {Page} page - Puppeteer page object + * @param {RuleObject} [overrides] - Axe rule overrides + * @returns {Promise} Axe Puppeteer instance */ async function axe(page, overrides = {}) { const reporter = new AxePuppeteer(page) @@ -23,7 +23,7 @@ async function axe(page, overrides = {}) { /** * Shared options for GOV.UK Frontend * - * @satisfies {import('axe-core').RunOptions} + * @satisfies {RunOptions} */ const options = { runOnly: { @@ -101,11 +101,11 @@ async function axe(page, overrides = {}) { * functions as nested context values aren't passed into Puppeteer correctly * * @template {object} HandlerContext - * @param {import('puppeteer').Page} page - Puppeteer page object + * @param {Page} page - Puppeteer page object * @param {string} [componentName] - The kebab-cased name of the component * @param {MacroRenderOptions} [renderOptions] - Nunjucks macro render options * @param {BrowserRenderOptions} [browserOptions] - Puppeteer browser render options - * @returns {Promise} Puppeteer page object + * @returns {Promise} Puppeteer page object */ async function render(page, componentName, renderOptions, browserOptions) { await page.setRequestInterception(true) @@ -225,7 +225,7 @@ async function render(page, componentName, renderOptions, browserOptions) { * - Responds to file:// asset requests (web fonts etc) * - Skips unknown requests * - * @param {import('puppeteer').HTTPRequest} request - Puppeteer HTTP request + * @param {HTTPRequest} request - Puppeteer HTTP request * @returns {Promise} */ async function requestHandler(request) { @@ -250,11 +250,11 @@ async function requestHandler(request) { /** * Navigate to path * - * @param {import('puppeteer').Page} page - Puppeteer page object + * @param {Page} page - Puppeteer page object * @param {URL | string} path - Path or URL to navigate to * @param {object} [options] - Navigation options * @param {URL} [options.baseURL] - Base URL to override - * @returns {Promise} Puppeteer page object + * @returns {Promise} Puppeteer page object */ async function goTo(page, path, options) { const { href, pathname } = !(path instanceof URL) @@ -278,11 +278,11 @@ async function goTo(page, path, options) { /** * Navigate to example * - * @param {import('puppeteer').Browser} browser - Puppeteer browser object + * @param {Browser} browser - Puppeteer browser object * @param {string} exampleName - Example name * @param {object} [options] - Navigation options * @param {URL} [options.baseURL] - Base URL to override - * @returns {Promise} Puppeteer page object + * @returns {Promise} Puppeteer page object */ async function goToExample(browser, exampleName, options) { return goTo(await browser.newPage(), `/examples/${exampleName}`, options) @@ -291,10 +291,10 @@ async function goToExample(browser, exampleName, options) { /** * Navigate to component preview page * - * @param {import('puppeteer').Browser} browser - Puppeteer browser object + * @param {Browser} browser - Puppeteer browser object * @param {string} [componentName] - Component name * @param {Parameters[1]} [options] - Navigation options - * @returns {Promise} Puppeteer page object + * @returns {Promise} Puppeteer page object */ async function goToComponent(browser, componentName, options) { return goTo(await browser.newPage(), getComponentURL(componentName, options)) @@ -336,7 +336,7 @@ function getComponentURL(componentName, options) { /** * Get property value for element * - * @param {import('puppeteer').ElementHandle} $element - Puppeteer element handle + * @param {ElementHandle} $element - Puppeteer element handle * @param {string} propertyName - Property name to return value for * @returns {Promise} Property value */ @@ -348,7 +348,7 @@ async function getProperty($element, propertyName) { /** * Get attribute value for element * - * @param {import('puppeteer').ElementHandle} $element - Puppeteer element handle + * @param {ElementHandle} $element - Puppeteer element handle * @param {string} attributeName - Attribute name to return value for * @returns {Promise} Attribute value */ @@ -359,8 +359,8 @@ function getAttribute($element, attributeName) { /** * Gets the accessible name of the given element, if it exists in the accessibility tree * - * @param {import('puppeteer').Page} page - Puppeteer page object - * @param {import('puppeteer').ElementHandle} $element - Puppeteer element handle + * @param {Page} page - Puppeteer page object + * @param {ElementHandle} $element - Puppeteer element handle * @returns {Promise} The element's accessible name * @throws {TypeError} If the element has no corresponding node in the accessibility tree */ @@ -377,7 +377,7 @@ async function getAccessibleName(page, $element) { /** * Check if element is visible * - * @param {import('puppeteer').ElementHandle} $element - Puppeteer element handle + * @param {ElementHandle} $element - Puppeteer element handle * @returns {Promise} Element visibility */ async function isVisible($element) { @@ -404,19 +404,13 @@ module.exports = { * @typedef {object} BrowserRenderOptions - Component render options * @property {Config[ConfigKey]} [config] - Component JavaScript config * @property {HandlerContext} [context] - Context options for custom functions - * @property {HandlerFunction} [beforeInitialisation] - Custom function to run before initialisation - * @property {HandlerFunction} [afterInitialisation] - Custom function to run after initialisation + * @property {EvaluateFuncWith} [beforeInitialisation] - Custom function to run before initialisation + * @property {EvaluateFuncWith} [afterInitialisation] - Custom function to run after initialisation */ /** - * Browser handler function with context options - * - * @template {object} HandlerContext - * @typedef {import('puppeteer').EvaluateFuncWith} HandlerFunction - */ - -/** - * @typedef {import('@govuk-frontend/lib/components').MacroRenderOptions} MacroRenderOptions - * @typedef {import('govuk-frontend').Config} Config - Config for all components via `initAll()` - * @typedef {import('govuk-frontend').ConfigKey} ConfigKey - Component config keys, e.g. `accordion` and `characterCount` + * @import { MacroRenderOptions } from '@govuk-frontend/lib/components' + * @import { AxeResults, RuleObject, RunOptions } from 'axe-core' + * @import { Config, ConfigKey } from 'govuk-frontend' + * @import { Browser, ElementHandle, EvaluateFuncWith, HTTPRequest, Page } from 'puppeteer' */ diff --git a/shared/tasks/browser.mjs b/shared/tasks/browser.mjs index b361dcddfc..7702848ddf 100644 --- a/shared/tasks/browser.mjs +++ b/shared/tasks/browser.mjs @@ -12,7 +12,7 @@ import puppeteer from 'puppeteer' /** * Puppeteer browser launcher * - * @returns {Promise} Puppeteer browser object + * @returns {Promise} Puppeteer browser object */ export async function launch() { await download() @@ -63,7 +63,7 @@ export async function screenshots() { * Send single component screenshots to Percy * for visual regression testing * - * @param {import('puppeteer').Browser} browser - Puppeteer browser object + * @param {Browser} browser - Puppeteer browser object * @param {string} componentName - Component name * @param {object} [options] - Component options * @param {string} options.exampleName - Example name @@ -100,7 +100,7 @@ export async function screenshotComponent(browser, componentName, options) { * Send single example screenshot to Percy * for visual regression testing * - * @param {import('puppeteer').Browser} browser - Puppeteer browser object + * @param {Browser} browser - Puppeteer browser object * @param {string} exampleName - Component name * @returns {Promise} */ @@ -121,3 +121,7 @@ export async function screenshotExample(browser, exampleName) { // Close page return page.close() } + +/** + * @import { Browser } from 'puppeteer' + */