Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

15.0 KB
Raw Blame
/**
 * Copyright (c) Microsoft Corporation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { InvalidSelectorError,  splitSelectorByFrame, stringifySelector, visitAllSelectorParts } from '@isomorphic/selectorParser';
import { asLocator } from '@isomorphic/locatorGenerators';

import { NonRecoverableDOMError } from './dom';
import { EvaluationStalledError } from './errors';

import type { ElementHandle, FrameExecutionContext } from './dom';
import type { Frame } from './frames';
import type { InjectedScript } from '@injected/injectedScript';
import type { JSHandle, SmartHandle, Unboxed } from './javascript';
import type * as types from './types';
import type { ParsedSelector } from '@isomorphic/selectorParser';


export type SelectorInfo = {
  parsed: ParsedSelector,
  world: types.World,
  strict: boolean,
};

type SelectorInFrame = {
  frame: Frame;
  info: SelectorInfo;
  frameVisible: boolean;
  scope?: ElementHandle;
};

type MatchedElementsCallback<Arg, R> = (data: { injected: InjectedScript, elements: Element[], info: SelectorInfo, frameVisible: boolean }, arg: Unboxed<Arg>) => R | Promise<R>;

export class FrameSelectors {
  readonly frame: Frame;

  constructor(frame: Frame) {
    this.frame = frame;
  }

  private _parseSelector(selector: string | ParsedSelector, strict: boolean | undefined): SelectorInfo {
    return this.frame._page.browserContext.selectors().parseSelector(selector, strict ?? !!this.frame._page.browserContext._options.strictSelectors);
  }

  async query(target: types.SelectorTarget & { mainWorld?: boolean }): Promise<ElementHandle<Element> | null> {
    const resolved = await this.callOnSelectorHandle(target, ({ elements }) => elements[0], {});
    if (!resolved)
      return null;
    const handle = resolved.result;
    const elementHandle = handle.asElement() as ElementHandle<Element> | null;
    if (!elementHandle) {
      handle.dispose();
      return null;
    }
    return adoptIfNeeded(elementHandle, await elementHandle._frame.mainContext());
  }

  async queryArrayInMainWorld(selector: string, scope?: ElementHandle): Promise<JSHandle<Element[]>> {
    const resolved = await this.callOnSelectorHandle({ selector, mainWorld: true, strict: false, scope }, ({ elements }) => elements, {});
    if (!resolved) {
      const context = await this.frame.context('main');
      return await context.evaluateHandle(() => []);
    }
    return resolved.result;
  }

  async queryCount(selector: string): Promise<number> {
    const resolved = await this.callOnSelector({ selector, strict: false }, ({ elements }) => elements.length, {});
    return resolved ? resolved.result : 0;
  }

  async queryAll(selector: string, scope?: ElementHandle): Promise<ElementHandle<Element>[]> {
    const resolved = await this.callOnSelectorHandle({ selector, strict: false, scope }, ({ elements }) => elements, {});
    if (!resolved)
      return [];

    const arrayHandle = resolved.result;
    const properties = await arrayHandle.internalGetProperties();
    const elementHandles: ElementHandle<Element>[] = [];
    for (const property of properties.values()) {
      const elementHandle = property.asElement() as ElementHandle<Element> | null;
      if (elementHandle)
        elementHandles.push(elementHandle);
      else
        property.dispose();
    }
    arrayHandle.dispose();
    if (!elementHandles.length)
      return [];

    // Note: adopting elements one by one may be slow. If we encounter the issue here,
    // we might introduce 'useMainContext' option or similar to speed things up.
    const targetContext = await elementHandles[0]._frame.mainContext();
    return Promise.all(elementHandles.map(handle => adoptIfNeeded(handle, targetContext)));
  }

  private _jumpToAriaRefFrameIfNeeded(selector: string, info: SelectorInfo, frame: Frame): Frame {
    if (info.parsed.parts[0].name !== 'aria-ref')
      return frame;
    const body = info.parsed.parts[0].body as string;
    const match = body.match(/^f(\d+)e\d+$/);
    if (!match)
      return frame;
    const frameSeq = +match[1];
    const jumptToFrame = this.frame._page.frameManager.frames().find(frame => frame.seq === frameSeq);
    if (!jumptToFrame)
      throw new InvalidSelectorError(`Invalid frame in aria-ref selector "${selector}"`);
    return jumptToFrame;
  }

  async resolveFramesForSelector(target: types.SelectorTarget & { anyFrame?: boolean }): Promise<SelectorInFrame[]> {
    const { selector, scope } = target;
    const { anyFrame, chunks } = splitSelectorByFrame(selector);
    for (const chunk of chunks) {
      visitAllSelectorParts(chunk, (part, nested) => {
        if (nested && part.name === 'internal:control' && part.body === 'enter-frame') {
          const locator = asLocator(this.frame._page.browserContext._browser.sdkLanguage(), selector);
          throw new InvalidSelectorError(`Frame locators are not allowed inside composite locators, while querying "${locator}"`);
        }
        if (nested && part.name === 'internal:control' && part.body === 'any-frame') {
          const locator = asLocator(this.frame._page.browserContext._browser.sdkLanguage(), selector);
          throw new InvalidSelectorError(`frameLocator() is not allowed inside composite locators, while querying "${locator}"`);
        }
      });
    }

    if (!anyFrame && !target.anyFrame) {
      const result = await this._resolveChainedSelector(this.frame, target, chunks, false /* noStall */);
      return result ? [result] : [];
    }

    const result: SelectorInFrame[] = [];
    const seenFrames = new Set<Frame>();
    for (const { frame: startFrame, frameVisible } of await this._anyFrameCandidates(scope)) {
      const resolved = await this._resolveChainedSelector(startFrame, startFrame === this.frame ? target : { ...target, scope: undefined }, chunks, startFrame !== this.frame /* noStall */, frameVisible);
      // Different starting frames may resolve into the same frame, e.g. with an aria-ref selector.
      if (!resolved || seenFrames.has(resolved.frame))
        continue;
      seenFrames.add(resolved.frame);
      result.push(resolved);
    }
    return result;
  }

  // All the frames the selector may start in: the frame subtree, restricted to the scope when given.
  private async _anyFrameCandidates(scope: ElementHandle | undefined): Promise<{ frame: Frame, frameVisible: boolean }[]> {
    const result: { frame: Frame, frameVisible: boolean }[] = [];
    const info = this._parseSelector('css=frame,iframe', false);
    const collectSubtree = async (frame: Frame, frameVisible: boolean, scope: ElementHandle | undefined) => {
      result.push({ frame, frameVisible });
      const childFrames = await this._queryFrames(frame, info, scope, true /* noStall */, frameVisible);
      for (const childFrame of childFrames ?? [])
        await collectSubtree(childFrame.frame, childFrame.frameVisible, undefined);
    };
    await collectSubtree(this.frame, true, scope);
    return result;
  }

  private async _queryFrames(frame: Frame, info: SelectorInfo, scope: ElementHandle | undefined, noStall: boolean, parentFrameVisible: boolean): Promise<{ frame: Frame, frameVisible: boolean }[] | null> {
    const context = noStall ? frame.existingContext(info.world) : await frame.context(info.world);
    if (!context)
      return null;
    const query = async () => {
      const injected = await context.injectedScript();
      const arrayHandle = await injected.evaluateHandle((injected, { info, scope, selectorString }) => {
        const elements = injected.querySelectorAll(info.parsed, scope || document);
        if (info.strict && elements.length > 1)
          throw injected.strictModeViolationError(info.parsed, elements);
        for (const element of elements) {
          if (element.nodeName !== 'IFRAME' && element.nodeName !== 'FRAME')
            throw injected.createStacklessError(`Selector "${selectorString}" resolved to ${injected.previewNode(element)}, <iframe> was expected`);
        }
        return elements;
      }, { info, scope, selectorString: stringifySelector(info.parsed) });
      const visible = parentFrameVisible ? await injected.evaluate((injected, elements) => elements.map(element => injected.utils.isElementVisible(element)), arrayHandle) : [];
      const properties = await arrayHandle.internalGetProperties();
      arrayHandle.dispose();
      const result: { frame: Frame, frameVisible: boolean }[] = [];
      let visibleIndex = 0;
      for (const property of properties.values()) {
        const handle = property.asElement() as ElementHandle<Element> | null;
        const contentFrame = handle ? await frame._page.delegate.getContentFrame(handle) : null;
        property.dispose();
        if (contentFrame)
          result.push({ frame: contentFrame, frameVisible: parentFrameVisible && visible[visibleIndex] === true });
        ++visibleIndex;
      }
      return result;
    };
    if (!noStall)
      return await query();
    return await frame.raceAgainstEvaluationStallingEvents(query).catch(e => {
      if (e instanceof EvaluationStalledError)
        return null;
      throw e;
    });
  }

  private async _resolveChainedSelector(startFrame: Frame, target: types.SelectorTarget, frameChunks: ParsedSelector[], noStall: boolean, startFrameVisible = true): Promise<SelectorInFrame | null> {
    const { selector } = target;
    let scope = target.scope;
    let frame = startFrame;
    let frameVisible = startFrameVisible;
    for (let i = 0; i < frameChunks.length - 1; ++i) {
      const info = this._parseSelector(frameChunks[i], target.strict);
      frame = this._jumpToAriaRefFrameIfNeeded(selector, info, frame);
      const frames = await this._queryFrames(frame, info, i === 0 ? scope : undefined, noStall, frameVisible);
      if (!frames?.length)
        return null;
      frame = frames[0].frame;
      frameVisible = frames[0].frameVisible;
    }
    // If we end up in the different frame, we should start from the frame root, so throw away the scope.
    if (frame !== startFrame)
      scope = undefined;
    const lastChunk = frame.selectors._parseSelector(frameChunks[frameChunks.length - 1], target.strict);
    frame = this._jumpToAriaRefFrameIfNeeded(selector, lastChunk, frame);
    return { frame, info: lastChunk, scope, frameVisible };
  }

  private async _callOnSelectorInternal<Arg, R>(
    target: types.SelectorTarget & { mainWorld?: boolean, callWithoutMatches?: boolean, markTargets?: 'all' | 'first' | 'none' },
    pageFunction: MatchedElementsCallback<Arg, R>,
    arg: Arg,
    returnByValue: boolean,
  ): Promise<{ frame: Frame, info: SelectorInfo, frameVisible: boolean, result: R | SmartHandle<R> } | null> {
    const resolved = await this.resolveFramesForSelector(target);
    let aggregatedResult: { frame: Frame, info: SelectorInfo, frameVisible: boolean, result: R | SmartHandle<R> } | null = null;
    const noStall = resolved.length > 1;
    for (const { frame, info, scope, frameVisible } of resolved) {
      const world = target.mainWorld ? 'main' : info.world;
      const context = noStall ? frame.existingContext(world) : await frame.context(world);
      if (!context)
        continue;
      const getResult = async () => {
        const injected = await context.injectedScript();
        const method = returnByValue ? 'evaluate' : 'evaluateHandle';
        const evalResult = await injected[method]((injected, params) => {
          const elements = injected.querySelectorAll(params.info.parsed, params.scope || document);
          if (params.markTargets === 'all')
            injected.markTargetElements(new Set(elements));
          else if (params.markTargets === 'first' && elements.length)
            injected.markTargetElements(new Set([elements[0]]));
          else if (params.markTargets === 'first')
            injected.markTargetElements(new Set());
          injected.checkDeprecatedSelectorUsage(params.info.parsed, elements);
          if (params.info.strict && elements.length > 1)
            throw injected.strictModeViolationError(params.info.parsed, elements);
          if (!elements.length && !params.callWithoutMatches)
            return '--playwright--no--result--value--';
          const func = injected.eval('(' + params.functionText + ')') as MatchedElementsCallback<Arg, R>;
          return func({ injected, elements, info: params.info, frameVisible: params.frameVisible }, params.arg);
        }, { info, scope, frameVisible, functionText: String(pageFunction), arg, callWithoutMatches: target.callWithoutMatches, markTargets: target.markTargets, returnByValue });
        if (returnByValue && evalResult === '--playwright--no--result--value--')
          return;
        if (!returnByValue && (evalResult as JSHandle)._value === '--playwright--no--result--value--') {
          (evalResult as JSHandle).dispose();
          return;
        }
        return { result: evalResult as R | SmartHandle<R> };
      };
      const maybeResult = noStall ? await frame.raceAgainstEvaluationStallingEvents(getResult).catch(e => {
        if (e instanceof EvaluationStalledError)
          return;
        throw e;
      }) : await getResult();
      if (!maybeResult)
        continue;
      if (aggregatedResult)
        throw new NonRecoverableDOMError(`frameLocator() matched elements in multiple frames.`);
      aggregatedResult = { frame, info, frameVisible, result: maybeResult.result };
    }
    return aggregatedResult;
  }

  async callOnSelector<Arg, R>(
    target: types.SelectorTarget & { mainWorld?: boolean, callWithoutMatches?: boolean, markTargets?: 'all' | 'first' | 'none' },
    pageFunction: MatchedElementsCallback<Arg, R>,
    arg: Arg,
  ): Promise<{ frame: Frame, info: SelectorInfo, frameVisible: boolean, result: R } | null> {
    const result = await this._callOnSelectorInternal(target, pageFunction, arg, true /* returnByValue */);
    return result as { frame: Frame, info: SelectorInfo, frameVisible: boolean, result: R } | null;
  }

  async callOnSelectorHandle<Arg, R>(
    target: types.SelectorTarget & { mainWorld?: boolean, markTargets?: 'all' | 'first' | 'none' },
    pageFunction: MatchedElementsCallback<Arg, R>,
    arg: Arg,
  ): Promise<{ frame: Frame, info: SelectorInfo, frameVisible: boolean, result: SmartHandle<R> } | null> {
    const result = await this._callOnSelectorInternal({ ...target, callWithoutMatches: false }, pageFunction, arg, false /* returnByValue */);
    return result as { frame: Frame, info: SelectorInfo, frameVisible: boolean, result: SmartHandle<R> } | null;
  }
}

async function adoptIfNeeded<T extends Node>(handle: ElementHandle<T>, context: FrameExecutionContext): Promise<ElementHandle<T>> {
  if (handle._context === context)
    return handle;
  const adopted = await handle._page.delegate.adoptElementHandle(handle, context);
  handle.dispose();
  return adopted;
}