feat(browser): support iframe locator with playwright provider (#8016)

Author: sheremet-va

docs/guide/browser/context.md

@@ -87,6 +87,12 @@ export const page: {
    * Wrap an HTML element in a `Locator`. When querying for elements, the search will always return this element.
    */
   elementLocator(element: Element): Locator
+  /**
+   * The iframe locator. This is a document locator that enters the iframe body
+   * and works similarly to the `page` object.
+   * **Warning:** At the moment, this is supported only by the `playwright` provider.
+   */
+  frameLocator(iframeElement: Locator): FrameLocator
 
   /**
    * Locator APIs. See its documentation for more details.
@@ -110,8 +116,37 @@ Note that `screenshot` will always return a base64 string if `save` is set to `f
 The `path` is also ignored in that case.
 :::
 
+### frameLocator
+
+```ts
+function frameLocator(iframeElement: Locator): FrameLocator
+```
+
+The `frameLocator` method returns a `FrameLocator` instance that can be used to find elements inside the iframe.
+
+The frame locator is similar to `page`. It does not refer to the Iframe HTML element, but to the iframe's document.
+
+```ts
+const frame = page.frameLocator(
+  page.getByTestId('iframe')
+)
+
+await frame.getByText('Hello World').click() // ✅
+await frame.click() // ❌ Not available
+```
+
+::: danger IMPORTANT
+At the moment, the `frameLocator` method is only supported by the `playwright` provider.
+
+The interactive methods (like `click` or `fill`) are always available on elements within the iframe, but assertions with `expect.element` require the iframe to have the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).
+:::
+
 ## `cdp`
 
+```ts
+function cdp(): CDPSession
+```
+
 The `cdp` export returns the current Chrome DevTools Protocol session. It is mostly useful to library authors to build tools on top of it.
 
 ::: warning

packages/browser/context.d.ts

@@ -455,6 +455,8 @@ interface LocatorSelectors {
   getByTestId: (text: string | RegExp) => Locator
 }
 
+export interface FrameLocator extends LocatorSelectors {}
+
 export interface Locator extends LocatorSelectors {
   /**
    * Selector string that will be used to locate the element by the browser provider.
@@ -701,6 +703,25 @@ export interface BrowserPage extends LocatorSelectors {
    * @see {@link https://vitest.dev/guide/browser/locators}
    */
   elementLocator(element: Element): Locator
+  /**
+   * The iframe locator. This is a document locator that enters the iframe body
+   * and works similarly to the `page` object.
+   *
+   * As the first argument, pass down the locator to the `<iframe>` element itself.
+   *
+   * **Warning:** At the moment, this is supported only by the `playwright` provider.
+   * @example
+   * ```ts
+   * const frame = page.frameLocator(
+   *   page.getByTestId('iframe')
+   * )
+   *
+   * await frame.getByText('Hello World').click()
+   * ```
+   * @param locator The locator object.
+   * @see {@link https://vitest.dev/guide/browser/locators}
+   */
+  frameLocator(locator: Locator): FrameLocator
 }
 
 export interface BrowserLocators {

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

@@ -314,31 +314,34 @@ export const page: BrowserPage = {
     ))
   },
   getByRole() {
-    throw new Error(`Method "getByRole" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "getByRole" is not supported by the "${provider}" provider.`)
   },
   getByLabelText() {
-    throw new Error(`Method "getByLabelText" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "getByLabelText" is not supported by the "${provider}" provider.`)
   },
   getByTestId() {
-    throw new Error(`Method "getByTestId" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "getByTestId" is not supported by the "${provider}" provider.`)
   },
   getByAltText() {
-    throw new Error(`Method "getByAltText" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "getByAltText" is not supported by the "${provider}" provider.`)
   },
   getByPlaceholder() {
-    throw new Error(`Method "getByPlaceholder" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "getByPlaceholder" is not supported by the "${provider}" provider.`)
   },
   getByText() {
-    throw new Error(`Method "getByText" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "getByText" is not supported by the "${provider}" provider.`)
   },
   getByTitle() {
-    throw new Error(`Method "getByTitle" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "getByTitle" is not supported by the "${provider}" provider.`)
   },
   elementLocator() {
-    throw new Error(`Method "elementLocator" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "elementLocator" is not supported by the "${provider}" provider.`)
+  },
+  frameLocator() {
+    throw new Error(`Method "frameLocator" is not supported by the "${provider}" provider.`)
   },
   _createLocator() {
-    throw new Error(`Method "_createLocator" is not implemented in the "${provider}" provider.`)
+    throw new Error(`Method "_createLocator" is not supported by the "${provider}" provider.`)
   },
   extend(methods) {
     for (const key in methods) {

packages/browser/src/client/tester/expect/toHaveAccessibleDescription.ts

@@ -25,6 +25,7 @@ export default function toHaveAccessibleDescription(
 ): ExpectationResult {
   const htmlElement = getElementFromUserInput(actual, toHaveAccessibleDescription, this)
   const actualAccessibleDescription = getElementAccessibleDescription(htmlElement, false)
+  const defaultView = htmlElement.ownerDocument.defaultView || window
 
   const missingExpectedValue = arguments.length === 1
 
@@ -36,7 +37,7 @@ export default function toHaveAccessibleDescription(
   }
   else {
     pass
-      = expectedAccessibleDescription instanceof RegExp
+      = expectedAccessibleDescription instanceof defaultView.RegExp
         ? expectedAccessibleDescription.test(actualAccessibleDescription)
         : this.equals(
             actualAccessibleDescription,

packages/browser/src/client/tester/expect/toHaveAccessibleErrorMessage.ts

@@ -25,6 +25,7 @@ export default function toHaveAccessibleErrorMessage(
 ): ExpectationResult {
   const htmlElement = getElementFromUserInput(actual, toHaveAccessibleErrorMessage, this)
   const actualAccessibleErrorMessage = getElementAccessibleErrorMessage(htmlElement) ?? ''
+  const defaultView = htmlElement.ownerDocument.defaultView || window
 
   const missingExpectedValue = arguments.length === 1
 
@@ -36,7 +37,7 @@ export default function toHaveAccessibleErrorMessage(
   }
   else {
     pass
-      = expectedAccessibleErrorMessage instanceof RegExp
+      = expectedAccessibleErrorMessage instanceof defaultView.RegExp
         ? expectedAccessibleErrorMessage.test(actualAccessibleErrorMessage)
         : this.equals(
             actualAccessibleErrorMessage,

packages/browser/src/client/tester/expect/toHaveAccessibleName.ts

@@ -26,6 +26,7 @@ export default function toHaveAccessibleName(
   const htmlElement = getElementFromUserInput(actual, toHaveAccessibleName, this)
   const actualAccessibleName = getElementAccessibleName(htmlElement, false)
   const missingExpectedValue = arguments.length === 1
+  const defaultView = htmlElement.ownerDocument.defaultView || window
 
   let pass = false
   if (missingExpectedValue) {
@@ -35,7 +36,7 @@ export default function toHaveAccessibleName(
   }
   else {
     pass
-      = expectedAccessibleName instanceof RegExp
+      = expectedAccessibleName instanceof defaultView.RegExp
         ? expectedAccessibleName.test(actualAccessibleName)
         : this.equals(actualAccessibleName, expectedAccessibleName, this.customTesters)
   }

packages/browser/src/client/tester/expect/toHaveFormValues.ts

@@ -25,7 +25,9 @@ export default function toHaveFormValues(
 ): ExpectationResult {
   const formElement = getElementFromUserInput(actual, toHaveFormValues, this)
 
-  if (!(formElement instanceof HTMLFieldSetElement) && !(formElement instanceof HTMLFormElement)) {
+  const defaultView = formElement.ownerDocument.defaultView || window
+
+  if (!(formElement instanceof defaultView.HTMLFieldSetElement) && !(formElement instanceof defaultView.HTMLFormElement)) {
     throw new TypeError(`toHaveFormValues must be called on a form or a fieldset, instead got ${getTag(formElement)}`)
   }
 

packages/browser/src/client/tester/expect/utils.ts

@@ -26,9 +26,11 @@ export function getElementFromUserInput(
     elementOrLocator = elementOrLocator.element()
   }
 
+  const defaultView = elementOrLocator?.ownerDocument?.defaultView || window
+
   if (
-    elementOrLocator instanceof HTMLElement
-    || elementOrLocator instanceof SVGElement
+    elementOrLocator instanceof defaultView.HTMLElement
+    || elementOrLocator instanceof defaultView.SVGElement
   ) {
     return elementOrLocator
   }
@@ -49,8 +51,10 @@ export function getNodeFromUserInput(
     elementOrLocator = elementOrLocator.element()
   }
 
+  const defaultView = elementOrLocator.ownerDocument?.defaultView || window
+
   if (
-    elementOrLocator instanceof Node
+    elementOrLocator instanceof defaultView.Node
   ) {
     return elementOrLocator
   }

packages/browser/src/client/tester/locators/playwright.ts

@@ -52,6 +52,11 @@ page.extend({
       element,
     )
   },
+  frameLocator(locator: Locator) {
+    return new PlaywrightLocator(
+      `${locator.selector} >> internal:control=enter-frame`,
+    )
+  },
 })
 
 class PlaywrightLocator extends Locator {

test/browser/test/iframe.test.ts

@@ -0,0 +1,15 @@
+import { page, server } from '@vitest/browser/context'
+import { expect, test } from 'vitest'
+
+test.runIf(server.provider === 'playwright')('locates an iframe', async () => {
+  const iframe = document.createElement('iframe')
+  iframe.setAttribute('data-testid', 'iframe')
+  iframe.srcdoc = '<div onclick="console.log">Hello World!</div>'
+  document.body.append(iframe)
+  const frame = page.frameLocator(
+    page.getByTestId('iframe'),
+  )
+
+  await frame.getByText('Hello World').click()
+  await expect.element(frame.getByText('Hello World')).toHaveTextContent('Hello World')
+})