@elastic/synthetics 1.0.0-beta.8 → 1.0.0

package/src/common_types.ts

@@ -23,12 +23,26 @@
  *
  */
 
-import { BrowserContextOptions, LaunchOptions } from 'playwright-chromium';
-import { Protocol } from 'playwright-chromium/types/protocol';
+import {
+  BrowserContextOptions,
+  LaunchOptions,
+  CDPSession,
+  ChromiumBrowser,
+  ChromiumBrowserContext,
+  Page,
+  APIRequestContext,
+} from 'playwright-chromium';
 import { Step } from './dsl';
-import { reporters } from './reporters';
+import { BuiltInReporterName, ReporterInstance } from './reporters';
+import { MonitorConfig } from './dsl/monitor';
 
 export type VoidCallback = () => void;
+export type Location = {
+  file: string;
+  line: number;
+  column: number;
+};
+
 export type Params = Record<string, any>;
 export type HooksArgs = {
   env: string;
@@ -36,7 +50,21 @@ export type HooksArgs = {
 };
 export type HooksCallback = (args: HooksArgs) => void;
 export type StatusValue = 'succeeded' | 'failed' | 'skipped';
-export type Reporters = keyof typeof reporters;
+
+export type NetworkConditions = {
+  offline: boolean;
+  downloadThroughput: number;
+  uploadThroughput: number;
+  latency: number;
+};
+
+export type Driver = {
+  browser: ChromiumBrowser;
+  context: ChromiumBrowserContext;
+  page: Page;
+  client: CDPSession;
+  request: APIRequestContext;
+};
 
 export type TraceOutput = {
   name: string;
@@ -74,26 +102,69 @@ export type BrowserInfo = {
   version: string;
 };
 
+export type Screenshot = {
+  timestamp: number;
+  step: Step;
+  data: string;
+};
+
+export type SecurityDetails = {
+  issuer?: string;
+  protocol?: string;
+  subjectName?: string;
+  validFrom?: number;
+  validTo?: number;
+};
+
+export type Request = {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  // Total size in bytes of the request (body and headers)
+  bytes?: number;
+  body?: {
+    // Size in bytes of the request body
+    bytes: number;
+  };
+  referrer?: string;
+};
+
+export type Response = {
+  url?: string;
+  status: number;
+  statusText?: string;
+  mimeType?: string;
+  headers: Record<string, string>;
+  // Total size in bytes of the response (body and headers)
+  bytes?: number;
+  body?: {
+    // Size in bytes of the response body
+    bytes: number;
+  };
+  transferSize?: number;
+  redirectURL?: string;
+  securityDetails?: SecurityDetails;
+  remoteIPAddress?: string;
+  remotePort?: number;
+  fromServiceWorker?: boolean;
+};
+
 export type NetworkInfo = {
   url: string;
   browser: BrowserInfo;
-  method: string;
   type: string;
-  request: Protocol.Network.Request;
-  response?: Protocol.Network.Response;
+  request: Request;
+  response: Response;
   isNavigationRequest: boolean;
   requestSentTime: number;
   loadEndTime: number;
   responseReceivedTime: number;
-  status: number;
   resourceSize: number;
   transferSize: number;
-  timings?: {
+  timings: {
     blocked: number;
-    queueing: number;
     dns: number;
     ssl: number;
-    proxy: number;
     connect: number;
     send: number;
     wait: number;
@@ -102,9 +173,12 @@ export type NetworkInfo = {
   };
 } & DefaultPluginOutput;
 
+export type PageMetrics = Record<string, number>;
+
 export type BrowserMessage = {
   text: string;
   type: string;
+  error?: Error;
 } & DefaultPluginOutput;
 
 export type PluginOutput = {
@@ -117,39 +191,122 @@ export type PluginOutput = {
 
 export type ScreenshotOptions = 'on' | 'off' | 'only-on-failure';
 
-export type CliArgs = {
-  capability?: Array<string>;
-  config?: string;
-  outfd?: number;
-  headless?: boolean;
+export type ThrottlingOptions = {
+  download?: number;
+  upload?: number;
+  latency?: number;
+};
+
+type BaseArgs = {
+  params?: Params;
   screenshots?: ScreenshotOptions;
-  ssblocks?: boolean;
-  metrics?: boolean;
-  filmstrips?: boolean;
-  trace?: boolean;
   dryRun?: boolean;
-  network?: boolean;
-  pauseOnError?: boolean;
-  reporter?: Reporters;
+  match?: string;
+  tags?: Array<string>;
+  outfd?: number;
   wsEndpoint?: string;
+  pauseOnError?: boolean;
+  ignoreHttpsErrors?: boolean;
+  playwrightOptions?: PlaywrightOptions;
+  quietExitCode?: boolean;
+  throttling?: MonitorConfig['throttling'];
+  schedule?: MonitorConfig['schedule'];
+  locations?: MonitorConfig['locations'];
+  privateLocations?: MonitorConfig['privateLocations'];
+};
+
+export type CliArgs = BaseArgs & {
+  config?: string;
+  reporter?: BuiltInReporterName;
+  pattern?: string;
+  inline?: boolean;
+  require?: Array<string>;
   sandbox?: boolean;
-  json?: boolean;
+  richEvents?: boolean;
+  capability?: Array<string>;
+  ignoreHttpsErrors?: boolean;
+};
+
+export type RunOptions = BaseArgs & {
+  metrics?: boolean;
+  ssblocks?: boolean;
+  network?: boolean;
+  trace?: boolean;
+  filmstrips?: boolean;
+  environment?: string;
+  playwrightOptions?: PlaywrightOptions;
+  networkConditions?: NetworkConditions;
+  reporter?: BuiltInReporterName | ReporterInstance;
+};
+
+export type PushOptions = Partial<ProjectSettings> & {
+  auth: string;
+  schedule?: MonitorConfig['schedule'];
+  locations?: MonitorConfig['locations'];
+  privateLocations?: MonitorConfig['privateLocations'];
+  yes?: boolean;
   pattern?: string;
-  inline: boolean;
   match?: string;
   tags?: Array<string>;
-  require: Array<string>;
-  debug?: boolean;
-  /**
-   * @deprecated use `params` instead
-   */
-  suiteParams?: Params;
-  params?: Params;
-  richEvents?: boolean;
 };
 
-export type PlaywrightOptions = LaunchOptions & BrowserContextOptions;
+export type ProjectSettings = {
+  id: string;
+  url: string;
+  space: string;
+};
+
+export type PlaywrightOptions = LaunchOptions &
+  BrowserContextOptions & {
+    testIdAttribute?: string;
+    actionTimeout?: number;
+    navigationTimeout?: number;
+  };
 export type SyntheticsConfig = {
   params?: Params;
   playwrightOptions?: PlaywrightOptions;
+  monitor?: MonitorConfig;
+  project?: ProjectSettings;
+};
+
+/** Runner Payload types */
+export type JourneyResult = {
+  status: StatusValue;
+  error?: Error;
+  networkinfo?: PluginOutput['networkinfo'];
+  browserconsole?: PluginOutput['browserconsole'];
+};
+
+export type StepResult = {
+  status: StatusValue;
+  url?: string;
+  error?: Error;
+  pagemetrics?: PageMetrics;
+  filmstrips?: PluginOutput['filmstrips'];
+  metrics?: PluginOutput['metrics'];
+  traces?: PluginOutput['traces'];
+};
+
+/** Reporter and Runner contract */
+export type StartEvent = {
+  numJourneys: number;
+  networkConditions?: NetworkConditions;
+};
+
+export type JourneyStartResult = {
+  timestamp: number;
+  params?: Params;
+};
+
+export type JourneyEndResult = JourneyStartResult &
+  JourneyResult & {
+    start: number;
+    end: number;
+    options: RunOptions;
+    timestamp: number;
+  };
+
+export type StepEndResult = StepResult & {
+  start: number;
+  end: number;
 };

package/src/config.ts

@@ -80,7 +80,7 @@ function getConfigFile(ext: string) {
   return 'synthetics.config' + ext;
 }
 
-function findSyntheticsConfig(resolvePath, cwd) {
+export function findSyntheticsConfig(resolvePath, cwd) {
   const configPath = ['.js', '.ts']
     .map(ext => resolve(resolvePath, getConfigFile(ext)))
     .find(isFile);

package/src/core/expect.ts

@@ -28,6 +28,8 @@ import type {
   AsymmetricMatcher,
   MatcherState,
   ExpectedAssertionsErrors,
+  Inverse,
+  PromiseMatchers,
 } from 'expect/build/types';
 
 // Copied source code from expect/build/types.d.ts
@@ -61,99 +63,122 @@ declare global {
       /**
        * If you know how to test something, `.not` lets you test its opposite.
        */
-      not: Matchers<R>;
+      not: Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Use resolves to unwrap the value of a fulfilled promise so any other
        * matcher can be chained. If the promise is rejected the assertion fails.
        */
-      resolves: Matchers<Promise<R>>;
+      resolves: Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Unwraps the reason of a rejected promise so any other matcher can be chained.
        * If the promise is fulfilled the assertion fails.
        */
-      rejects: Matchers<Promise<R>>;
+      rejects: Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Checks that a value is what you expect. It uses `===` to check strict equality.
        * Don't use `toBe` with floating-point numbers.
        */
-      toBe(expected: unknown): R;
+      toBe(
+        expected: unknown
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Using exact equality with floating point numbers is a bad idea.
        * Rounding means that intuitive things fail.
        * The default for numDigits is 2.
        */
-      toBeCloseTo(expected: number, numDigits?: number): R;
+      toBeCloseTo(
+        expected: number,
+        numDigits?: number
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Ensure that a variable is not undefined.
        */
-      toBeDefined(): R;
+      toBeDefined(): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * When you don't care what a value is, you just want to
        * ensure a value is false in a boolean context.
        */
-      toBeFalsy(): R;
+      toBeFalsy(): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * For comparing floating point numbers.
        */
-      toBeGreaterThan(expected: number | bigint): R;
+      toBeGreaterThan(
+        expected: number | bigint
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * For comparing floating point numbers.
        */
-      toBeGreaterThanOrEqual(expected: number | bigint): R;
+      toBeGreaterThanOrEqual(
+        expected: number | bigint
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Ensure that an object is an instance of a class.
        * This matcher uses `instanceof` underneath.
        */
       /* eslint-disable-next-line */
-      toBeInstanceOf(expected: Function): R;
+      toBeInstanceOf(
+        expected: unknown
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * For comparing floating point numbers.
        */
-      toBeLessThan(expected: number | bigint): R;
+      toBeLessThan(
+        expected: number | bigint
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * For comparing floating point numbers.
        */
-      toBeLessThanOrEqual(expected: number | bigint): R;
+      toBeLessThanOrEqual(
+        expected: number | bigint
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * This is the same as `.toBe(null)` but the error messages are a bit nicer.
        * So use `.toBeNull()` when you want to check that something is null.
        */
-      toBeNull(): R;
+      toBeNull(): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Use when you don't care what a value is, you just want to ensure a value
        * is true in a boolean context. In JavaScript, there are six falsy values:
        * `false`, `0`, `''`, `null`, `undefined`, and `NaN`. Everything else is truthy.
        */
-      toBeTruthy(): R;
+      toBeTruthy(): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Used to check that a variable is undefined.
        */
-      toBeUndefined(): R;
+      toBeUndefined(): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Used to check that a variable is NaN.
        */
-      toBeNaN(): R;
+      toBeNaN(): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Used when you want to check that an item is in a list.
        * For testing the items in the list, this uses `===`, a strict equality check.
        */
-      toContain(expected: unknown): R;
+      toContain(
+        expected: unknown
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Used when you want to check that an item is in a list.
        * For testing the items in the list, this  matcher recursively checks the
        * equality of all fields, rather than checking for object identity.
        */
-      toContainEqual(expected: unknown): R;
+      toContainEqual(
+        expected: unknown
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Used when you want to check that two objects have the same value.
        * This matcher recursively checks the equality of all fields, rather than checking for object identity.
        */
-      toEqual(expected: unknown): R;
+      toEqual(
+        expected: unknown
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Used to check that an object has a `.length` property
        * and it is set to a certain numeric value.
        */
-      toHaveLength(expected: number): R;
+      toHaveLength(
+        expected: number
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Use to check if property at provided reference keyPath exists for an object.
        * For checking deeply nested properties in an object you may use dot notation or an array containing
@@ -167,19 +192,28 @@ declare global {
        *
        * expect(houseForSale).toHaveProperty('kitchen.area', 20);
        */
-      toHaveProperty(keyPath: string | Array<string>, value?: unknown): R;
+      toHaveProperty(
+        keyPath: string | Array<string>,
+        value?: unknown
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Check that a string matches a regular expression.
        */
-      toMatch(expected: string | RegExp): R;
+      toMatch(
+        expected: string | RegExp
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Used to check that a JavaScript object matches a subset of the properties of an object
        */
-      toMatchObject(expected: Record<string, unknown> | Array<unknown>): R;
+      toMatchObject(
+        expected: Record<string, unknown> | Array<unknown>
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
       /**
        * Use to test that objects have the same types as well as structure.
        */
-      toStrictEqual(expected: unknown): R;
+      toStrictEqual(
+        expected: unknown
+      ): Matchers<R> & Inverse<Matchers<R>> & PromiseMatchers;
     }
   }
 }

package/src/core/gatherer.ts

@@ -24,22 +24,18 @@
  */
 
 import {
-  CDPSession,
   chromium,
   ChromiumBrowser,
-  ChromiumBrowserContext,
-  Page,
+  BrowserContext,
+  request as apiRequest,
+  selectors,
 } from 'playwright-chromium';
 import { PluginManager } from '../plugins';
-import { RunOptions } from './runner';
 import { log } from './logger';
+import { Driver, NetworkConditions, RunOptions } from '../common_types';
 
-export type Driver = {
-  browser: ChromiumBrowser;
-  context: ChromiumBrowserContext;
-  page: Page;
-  client: CDPSession;
-};
+// Default timeout for Playwright actions and Navigations
+const DEFAULT_TIMEOUT = 50000;
 
 /**
  * Purpose of the Gatherer is to set up the necessary browser driver
@@ -49,19 +45,93 @@ export class Gatherer {
   static browser: ChromiumBrowser;
 
   static async setupDriver(options: RunOptions): Promise<Driver> {
+    log('Gatherer: setup driver');
     const { wsEndpoint, playwrightOptions } = options;
+
     if (Gatherer.browser == null) {
       if (wsEndpoint) {
         log(`Gatherer: connecting to WS endpoint: ${wsEndpoint}`);
-        Gatherer.browser = await chromium.connect({ wsEndpoint });
+        Gatherer.browser = await chromium.connect(wsEndpoint);
       } else {
-        Gatherer.browser = await chromium.launch(playwrightOptions);
+        Gatherer.browser = await chromium.launch({
+          ...playwrightOptions,
+          args: [
+            ...(playwrightOptions?.headless ? ['--disable-gpu'] : []),
+            ...(playwrightOptions?.args ?? []),
+          ],
+        });
       }
     }
-    const context = await Gatherer.browser.newContext(playwrightOptions);
+    const context = await Gatherer.browser.newContext({
+      ...playwrightOptions,
+      userAgent: await Gatherer.getUserAgent(playwrightOptions?.userAgent),
+    });
+    // Set timeouts for actions and navigations
+    context.setDefaultTimeout(
+      playwrightOptions?.actionTimeout ?? DEFAULT_TIMEOUT
+    );
+    context.setDefaultNavigationTimeout(
+      playwrightOptions?.navigationTimeout ?? DEFAULT_TIMEOUT
+    );
+
+    // TODO: Network throttling via chrome devtools emulation is disabled for now.
+    // See docs/throttling.md for more details.
+    // Gatherer.setNetworkConditions(context, networkConditions);
+    if (playwrightOptions?.testIdAttribute) {
+      selectors.setTestIdAttribute(playwrightOptions.testIdAttribute);
+    }
+
     const page = await context.newPage();
     const client = await context.newCDPSession(page);
-    return { browser: Gatherer.browser, context, page, client };
+    const request = await apiRequest.newContext({ ...playwrightOptions });
+
+    // Register sig int handler to close the browser
+    process.on('SIGINT', async () => {
+      await Gatherer.closeBrowser();
+      process.exit(130);
+    });
+    return { browser: Gatherer.browser, context, page, client, request };
+  }
+
+  static async getUserAgent(userAgent?: string) {
+    if (!userAgent) {
+      const session = await Gatherer.browser.newBrowserCDPSession();
+      ({ userAgent } = await session.send('Browser.getVersion'));
+      return userAgent + ' Elastic/Synthetics';
+    }
+    return userAgent;
+  }
+
+  static setNetworkConditions(
+    context: BrowserContext,
+    networkConditions: NetworkConditions
+  ) {
+    if (networkConditions) {
+      context.on('page', page => {
+        const context = page.context();
+        const emulatePromise = context
+          .newCDPSession(page)
+          .then(client =>
+            client.send('Network.emulateNetworkConditions', networkConditions)
+          );
+        /**
+         * Guard against pages that gets closed before the emulation kicks to capture
+         * unhandled rejections from accessing the CDP session of closed page
+         */
+        Promise.race([
+          new Promise<void>(resolve => page.on('close', () => resolve())),
+          emulatePromise,
+        ]);
+      });
+    }
+  }
+
+  static async closeBrowser() {
+    log(`Gatherer: closing browser`);
+    if (Gatherer.browser) {
+      await Gatherer.browser.close();
+      Gatherer.browser = null;
+    }
   }
 
   /**
@@ -70,26 +140,23 @@ export class Gatherer {
    */
   static async beginRecording(driver: Driver, options: RunOptions) {
     log('Gatherer: started recording');
-    const { filmstrips, trace, network, metrics } = options;
+    const { network, metrics } = options;
     const pluginManager = new PluginManager(driver);
-    const plugins = [pluginManager.start('browserconsole')];
-    network && plugins.push(pluginManager.start('network'));
-    metrics && plugins.push(pluginManager.start('performance'));
-    if (filmstrips || trace) {
-      plugins.push(pluginManager.start('trace', { filmstrips, trace }));
-    }
+    pluginManager.registerAll(options);
+    const plugins = [await pluginManager.start('browserconsole')];
+    network && plugins.push(await pluginManager.start('network'));
+    metrics && plugins.push(await pluginManager.start('performance'));
     await Promise.all(plugins);
     return pluginManager;
   }
 
   static async dispose(driver: Driver) {
+    log(`Gatherer: closing all contexts`);
+    await driver.request.dispose();
     await driver.context.close();
   }
 
   static async stop() {
-    if (Gatherer.browser) {
-      await Gatherer.browser.close();
-      Gatherer.browser = null;
-    }
+    await Gatherer.closeBrowser();
   }
 }