feat(browser): expose utils.configurePrettyDOM (#9103)

Author: sheremet-va

docs/api/browser/context.md

@@ -191,3 +191,43 @@ export const server: {
   config: SerializedConfig
 }
 ```
+
+## `utils`
+
+Utility functions useful for custom render libraries.
+
+```ts
+export const utils: {
+  /**
+   * This is simillar to calling `page.elementLocator`, but it returns only
+   * locator selectors.
+   */
+  getElementLocatorSelectors(element: Element): LocatorSelectors
+  /**
+   * Prints prettified HTML of an element.
+   */
+  debug(
+    el?: Element | Locator | null | (Element | Locator)[],
+    maxLength?: number,
+    options?: PrettyDOMOptions,
+  ): void
+  /**
+   * Returns prettified HTML of an element.
+   */
+  prettyDOM(
+    dom?: Element | Locator | undefined | null,
+    maxLength?: number,
+    prettyFormatOptions?: PrettyDOMOptions,
+  ): string
+  /**
+   * Configures default options of `prettyDOM` and `debug` functions.
+   * This will also affect `vitest-browser-{framework}` package.
+   * @experimental
+   */
+  configurePrettyDOM(options: StringifyOptions): void
+  /**
+   * Creates "Cannot find element" error. Useful for custom locators.
+   */
+  getElementError(selector: string, container?: Element): Error
+}
+```

packages/browser/context.d.ts

@@ -753,17 +753,36 @@ export interface BrowserLocators {
 export type PrettyDOMOptions = Omit<StringifyOptions, 'maxLength'>
 
 export const utils: {
+  /**
+   * This is simillar to calling `page.elementLocator`, but it returns only
+   * locator selectors.
+   */
   getElementLocatorSelectors(element: Element): LocatorSelectors
+  /**
+   * Prints prettified HTML of an element.
+   */
   debug(
     el?: Element | Locator | null | (Element | Locator)[],
     maxLength?: number,
     options?: PrettyDOMOptions,
   ): void
+  /**
+   * Returns prettified HTML of an element.
+   */
   prettyDOM(
     dom?: Element | Locator | undefined | null,
     maxLength?: number,
     prettyFormatOptions?: PrettyDOMOptions,
   ): string
+  /**
+   * Configures default options of `prettyDOM` and `debug` functions.
+   * This will also affect `vitest-browser-{framework}` package.
+   * @experimental
+   */
+  configurePrettyDOM(options: StringifyOptions): void
+  /**
+   * Creates "Cannot find element" error. Useful for custom locators.
+   */
   getElementError(selector: string, container?: Element): Error
 }
 

packages/browser/src/client/tester/context.ts

@@ -406,6 +406,8 @@ function getElementLocatorSelectors(element: Element): LocatorSelectors {
 
 type PrettyDOMOptions = Omit<StringifyOptions, 'maxLength'>
 
+let defaultOptions: StringifyOptions | undefined
+
 function debug(
   el?: Element | Locator | null | (Element | Locator)[],
   maxLength?: number,
@@ -423,7 +425,7 @@ function debug(
 
 function prettyDOM(
   dom?: Element | Locator | undefined | null,
-  maxLength: number = Number(import.meta.env.DEBUG_PRINT_LIMIT ?? 7000),
+  maxLength: number = Number(defaultOptions?.maxLength ?? import.meta.env.DEBUG_PRINT_LIMIT ?? 7000),
   prettyFormatOptions: PrettyDOMOptions = {},
 ): string {
   if (maxLength === 0) {
@@ -447,6 +449,7 @@ function prettyDOM(
   const pretty = stringify(dom, Number.POSITIVE_INFINITY, {
     maxLength,
     highlight: true,
+    ...defaultOptions,
     ...prettyFormatOptions,
   })
   return dom.outerHTML.length > maxLength
@@ -460,9 +463,17 @@ function getElementError(selector: string, container: Element): Error {
   return error
 }
 
+/**
+ * @experimental
+ */
+function configurePrettyDOM(options: StringifyOptions) {
+  defaultOptions = options
+}
+
 export const utils = {
   getElementError,
   prettyDOM,
   debug,
   getElementLocatorSelectors,
+  configurePrettyDOM,
 }

test/browser/test/utils.test.ts

@@ -93,3 +93,19 @@ test('should be able to opt out of shadow DOM content', async () => {
 
   expect(await commands.stripVTControlCharacters(utils.prettyDOM(undefined, undefined, { printShadowRoot: false }))).toMatchSnapshot()
 })
+
+test('changing the defaults works', async () => {
+  utils.configurePrettyDOM({
+    maxDepth: 1,
+  })
+
+  const div = document.createElement('div')
+  div.innerHTML = '<div><div><div><div></div></div></div></div>'
+  document.body.append(div)
+
+  expect(await commands.stripVTControlCharacters(utils.prettyDOM(div))).toMatchInlineSnapshot(`
+    "<div>
+      <div … />
+    </div>"
+  `)
+})