Skip to content

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

6.2 KB
Raw Blame
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 *
 * 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 { EventEmitter } from 'events';

import { createGuid } from '@utils/crypto';
import { debugLogger } from '@utils/debugLogger';

import type { SerializedError } from './channels';
import type { Browser } from './browser';
import type { BrowserContext } from './browserContext';
import type { BrowserType } from './browserType';
import type { Dialog } from './dialog';
import type { Download } from './download';
import type { APIRequestContext } from './fetch';
import type { Frame } from './frames';
import type { Page, Worker } from './page';
import type { Playwright } from './playwright';
import type { Progress } from './progress';
import type * as types from './types';
import type { LogName } from '@utils/debugLogger';

export type Attribution = {
  playwright: Playwright;
  browserType?: BrowserType;
  browser?: Browser;
  context?: BrowserContext | APIRequestContext;
  page?: Page;
  frame?: Frame;
  worker?: Worker;
};


export type EventMap = Record<string | symbol, any[]>;

export class SdkObject<EM extends EventMap = EventMap> extends EventEmitter<EM> {
  guid: string;
  attribution: Attribution;
  instrumentation: Instrumentation;
  logName?: LogName;

  constructor(parent: SdkObject, guidPrefix?: string, guid?: string) {
    super();
    this.guid = guid || `${guidPrefix || ''}@${createGuid()}`;
    this.setMaxListeners(0);
    this.attribution = { ...parent.attribution };
    this.instrumentation = parent.instrumentation;
  }

  apiLog(message: string) {
    if (!this.attribution.playwright.options.isInternalPlaywright)
      debugLogger.log('api', message);
  }

  closeReason(): string | undefined {
    return this.attribution.worker?._closeReason ||
      this.attribution.page?._closeReason ||
      this.attribution.context?._closeReason ||
      this.attribution.browser?._closeReason;
  }
}

export function createRootSdkObject() {
  const fakeParent = { attribution: {}, instrumentation: createInstrumentation() };
  const root = new SdkObject(fakeParent as any);
  root.guid = '';
  return root;
}

export type AddListenerOptions = { order?: 'last' };

export type CallMetadata = {
  id: string;
  startTime: number;
  endTime: number;
  pauseStartTime?: number;
  pauseEndTime?: number;
  type: string;
  method: string;
  params: any;
  timeout?: number;
  title?: string;
  // Client is making an internal call that should not show up in
  // the inspector or trace.
  internal?: boolean;
  location?: { file: string, line?: number, column?: number };
  log: string[];
  error?: SerializedError;
  result?: any;
  objectId?: string;
};

export interface Instrumentation {
  addListener(listener: InstrumentationListener, context: BrowserContext | APIRequestContext | null, options?: AddListenerOptions): void;
  removeListener(listener: InstrumentationListener): void;
  onBeforeCall(progress: Progress, sdkObject: SdkObject, parentId?: string): Promise<void>;
  onBeforeInputAction(progress: Progress, sdkObject: SdkObject, point?: types.Point, box?: types.Rect): Promise<void>;
  onCallLog(sdkObject: SdkObject, metadata: CallMetadata, logName: string, message: string): void;
  onAfterCall(progress: Progress, sdkObject: SdkObject): Promise<void>;
  onPageOpen(page: Page): void;
  onPageWillClose(page: Page): Promise<void>;
  onPageDidClose(page: Page): void;
  onBrowserOpen(browser: Browser): void;
  onBrowserClose(browser: Browser): void;
  onDialog(dialog: Dialog): void;
  onDownload(page: Page, download: Download): void;
}

export interface InstrumentationListener {
  onBeforeCall?(progress: Progress, sdkObject: SdkObject, parentId?: string): Promise<void>;
  onBeforeInputAction?(progress: Progress, sdkObject: SdkObject, point?: types.Point, box?: types.Rect): Promise<void>;
  onCallLog?(sdkObject: SdkObject, metadata: CallMetadata, logName: string, message: string): void;
  onAfterCall?(progress: Progress, sdkObject: SdkObject): Promise<void>;
  onPageOpen?(page: Page): void;
  onPageWillClose?(page: Page): Promise<void>;
  onPageDidClose?(page: Page): void;
  onBrowserOpen?(browser: Browser): void;
  onBrowserClose?(browser: Browser): void;
  onDialog?(dialog: Dialog): void;
  onDownload?(page: Page, download: Download): void;
}

export function createInstrumentation(): Instrumentation {
  const listeners = new Map<InstrumentationListener, BrowserContext | APIRequestContext | null>();
  const lastListeners = new Map<InstrumentationListener, BrowserContext | APIRequestContext | null>();
  return new Proxy({}, {
    get: (obj: any, prop: string | symbol) => {
      if (typeof prop !== 'string')
        return obj[prop];
      if (prop === 'addListener') {
        return (listener: InstrumentationListener, context: BrowserContext | APIRequestContext | null, options?: AddListenerOptions) => {
          if (options?.order === 'last')
            lastListeners.set(listener, context);
          else
            listeners.set(listener, context);
        };
      }
      if (prop === 'removeListener') {
        return (listener: InstrumentationListener) => {
          listeners.delete(listener);
          lastListeners.delete(listener);
        };
      }
      if (!prop.startsWith('on'))
        return obj[prop];
      return async (...params: any[]) => {
        const sdkObject: SdkObject = params[0] instanceof SdkObject ? params[0] : params[1];
        for (const [listener, context] of listeners) {
          if (!context || sdkObject.attribution.context === context)
            await (listener as any)[prop]?.(...params);
        }
        for (const [listener, context] of lastListeners) {
          if (!context || sdkObject.attribution.context === context)
            await (listener as any)[prop]?.(...params);
        }
      };
    },
  });
}