@elastic/synthetics 1.0.0-beta.2 → 1.0.0-beta.22

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@elastic/synthetics",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.22",
   "description": "Elastic synthetic monitoring agent",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "prepublish": "npm run clean && npm run build",
     "build": "tsc",
     "watch": "tsc -w",
@@ -38,26 +38,37 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "commander": "^7.0.0",
+    "commander": "^9.0.0",
+    "deepmerge": "^4.2.2",
+    "expect": "^27.0.2",
     "http-proxy": "^1.18.1",
-    "kleur": "^4.1.3",
-    "playwright-chromium": "=1.11.0",
+    "kleur": "^4.1.4",
+    "micromatch": "^4.0.4",
+    "playwright-chromium": "=1.14.0",
+    "sharp": "^0.30.1",
     "snakecase-keys": "^3.2.1",
-    "sonic-boom": "^1.3.0",
-    "source-map-support": "^0.5.19",
-    "ts-node": "^9.1.1",
-    "typescript": "^4.1.3"
+    "sonic-boom": "^2.6.0",
+    "source-map-support": "^0.5.21",
+    "ts-node": "^10.5.0",
+    "typescript": "^4.5.5"
   },
   "devDependencies": {
-    "@types/jest": "^26.0.19",
+    "@types/jest": "^27.4.0",
+    "@types/micromatch": "^4.0.1",
     "@types/node": "^14.14.14",
-    "@typescript-eslint/eslint-plugin": "^3.10.1",
-    "@typescript-eslint/parser": "^3.10.1",
-    "eslint": "^7.15.0",
+    "@types/sharp": "^0.28.2",
+    "@typescript-eslint/eslint-plugin": "^5.0.0",
+    "@typescript-eslint/parser": "^5.0.0",
+    "eslint": "^8.0.1",
     "husky": "^4.3.6",
-    "jest": "^26.6.3",
+    "jest": "^27.4.5",
     "lint-staged": "^10.5.3",
-    "prettier": "^2.2.1",
-    "ts-jest": "^26.4.4"
+    "prettier": "^2.4.1",
+    "rimraf": "^3.0.2",
+    "ts-jest": "^27.1.2"
+  },
+  "engines": {
+    "node": ">14.14.0",
+    "npm": "6"
   }
 }

package/src/cli.ts

@@ -27,20 +27,21 @@
 
 import { stdin, cwd } from 'process';
 import { resolve } from 'path';
+import merge from 'deepmerge';
 import { step, journey } from './core';
 import { log } from './core/logger';
-import program from './parse_args';
-import { CliArgs } from './common_types';
+import program, { options } from './parse_args';
+import { expect } from './core/expect';
 import {
   findPkgJsonByTraversing,
   isDepInstalled,
   isDirectory,
   totalist,
+  parseNetworkConditions,
 } from './helpers';
 import { run } from './';
 import { readConfig } from './config';
 
-const options = program.opts() as CliArgs;
 const resolvedCwd = cwd();
 /**
  * Set debug based on DEBUG ENV and -d flags
@@ -52,9 +53,17 @@ if (process.env.DEBUG === namespace || Boolean(options.debug)) {
 }
 
 const loadInlineScript = source => {
-  const scriptFn = new Function('step', 'page', 'browser', 'params', source);
-  journey('inline', async ({ page, browser, params }) => {
-    scriptFn.apply(null, [step, page, browser, params]);
+  const scriptFn = new Function(
+    'step',
+    'page',
+    'context',
+    'browser',
+    'params',
+    'expect',
+    source
+  );
+  journey('inline', ({ page, context, browser, params }) => {
+    scriptFn.apply(null, [step, page, context, browser, params, expect]);
   });
 };
 
@@ -103,7 +112,7 @@ async function prepareSuites(inputs: string[]) {
      * the suites
      */
     findPkgJsonByTraversing(absPath, resolvedCwd);
-    if (await isDirectory(absPath)) {
+    if (isDirectory(absPath)) {
       await totalist(absPath, (rel, abs) => {
         if (pattern.test(rel) && !ignored.test(rel)) {
           addSuite(abs);
@@ -117,6 +126,25 @@ async function prepareSuites(inputs: string[]) {
 }
 
 (async () => {
+  /**
+   * Transform `.ts` files out of the box by invoking
+   * the `ts-node` via `transpile-only` mode that compiles
+   * TS files without doing any extensive type checks.
+   *
+   * We must register `ts-node` _before_ loading inline
+   * scripts too because otherwise we will not be able to
+   * require `.ts` configuration files.
+   */
+  /* eslint-disable-next-line @typescript-eslint/no-var-requires */
+  require('ts-node').register({
+    transpileOnly: true,
+    compilerOptions: {
+      esModuleInterop: true,
+      allowJs: true,
+      target: 'es2018',
+    },
+  });
+
   if (options.inline) {
     const source = await readStdin();
     loadInlineScript(source);
@@ -132,20 +160,6 @@ async function prepareSuites(inputs: string[]) {
         throw new Error(`cannot find module '${name}'`);
       }
     }
-    /**
-     * Transform `.ts` files out of the box by invoking
-     * the `ts-node` via `transpile-only` mode that compiles
-     * TS files without doing any extensive type checks
-     */
-    /* eslint-disable-next-line @typescript-eslint/no-var-requires */
-    require('ts-node').register({
-      transpileOnly: true,
-      compilerOptions: {
-        esModuleInterop: true,
-        allowJs: true,
-        target: 'es2018',
-      },
-    });
     /**
      * Handle piped files by reading the STDIN
      * ex: ls example/suites/*.js | npx @elastic/synthetics
@@ -159,40 +173,49 @@ async function prepareSuites(inputs: string[]) {
   }
 
   /**
-   * Use the NODE_ENV variable to control the environment if its not explicity
-   * passed from either CLI or through the API
+   * Use the NODE_ENV variable to control the environment
    */
-  const environment = options.environment || process.env['NODE_ENV'];
+  const environment = process.env['NODE_ENV'] || 'development';
   /**
    * Validate and handle configs
    */
-  const config = readConfig(environment, options.config);
-  const params = config.params || JSON.parse(options.suiteParams);
+  const config =
+    options.config || !options.inline
+      ? readConfig(environment, options.config)
+      : {};
+  const params = merge(config.params, options.params || {});
+
   /**
-   * use JSON reporter if json flag is enabled
+   * Favor playwright options passed via cli to inline playwright options
    */
-  const reporter = options.json ? 'json' : options.reporter;
+  const playwrightOptions = merge.all([
+    config.playwrightOptions || {},
+    options.playwrightOptions || {},
+    {
+      headless: options.headless,
+      chromiumSandbox: options.sandbox,
+      ignoreHTTPSErrors: options.ignoreHttpsErrors,
+    },
+  ]);
 
   const results = await run({
-    params: Object.freeze({ ...params, environment }),
-    reporter,
-    headless: options.headless,
-    screenshots: options.screenshots,
-    dryRun: options.dryRun,
-    journeyName: options.journeyName,
-    network: options.network,
-    pauseOnError: options.pauseOnError,
-    outfd: options.outfd,
-    metrics: options.metrics,
-    sandbox: options.sandbox,
+    params: Object.freeze(params),
+    networkConditions: options.throttling
+      ? parseNetworkConditions(options.throttling as string)
+      : undefined,
+    environment,
+    playwrightOptions,
+    ...options,
   });
 
-  /**
-   * Exit with error status if any journey fails
-   */
-  for (const result of Object.values(results)) {
-    if (result.status === 'failed') {
-      process.exit(1);
+  if (!options.quietExitCode) {
+    /**
+     * Exit with error status if any journey fails
+     */
+    for (const result of Object.values(results)) {
+      if (result.status === 'failed') {
+        process.exit(1);
+      }
     }
   }
 })().catch(e => {

package/src/common_types.ts

@@ -23,18 +23,65 @@
  *
  */
 
+import {
+  BrowserContextOptions,
+  LaunchOptions,
+  CDPSession,
+  ChromiumBrowser,
+  ChromiumBrowserContext,
+  Page,
+} from 'playwright-chromium';
 import { Protocol } from 'playwright-chromium/types/protocol';
 import { Step } from './dsl';
 import { reporters } from './reporters';
 
 export type VoidCallback = () => void;
+export type Params = Record<string, any>;
+export type NetworkConditions = {
+  offline: boolean;
+  downloadThroughput: number;
+  uploadThroughput: number;
+  latency: number;
+};
+export type HooksArgs = {
+  env: string;
+  params: Params;
+};
+export type HooksCallback = (args: HooksArgs) => void;
 export type StatusValue = 'succeeded' | 'failed' | 'skipped';
 export type Reporters = keyof typeof reporters;
 
-export type FilmStrip = {
-  snapshot: string;
-  ts: number;
-  startTime: number;
+export type Driver = {
+  browser: ChromiumBrowser;
+  context: ChromiumBrowserContext;
+  page: Page;
+  client: CDPSession;
+};
+
+export type TraceOutput = {
+  name: string;
+  type: string;
+  start: MetricDuration;
+  duration?: MetricDuration;
+  score?: number;
+};
+
+type MetricDuration = {
+  us: number;
+};
+
+export type PerfMetrics = {
+  fcp: MetricDuration;
+  lcp: MetricDuration;
+  dcl: MetricDuration;
+  load: MetricDuration;
+  cls: number;
+};
+
+export type Filmstrip = {
+  start: MetricDuration;
+  blob: string;
+  mime: string;
 };
 
 export type DefaultPluginOutput = {
@@ -47,18 +94,66 @@ 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;
+  protocol?: string;
+  status: number;
+  statusText?: string;
+  mimeType: string;
+  httpVersion?: 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;
+  timing?: Protocol.Network.ResourceTiming;
+};
+
 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?: {
@@ -75,25 +170,54 @@ export type NetworkInfo = {
   };
 } & DefaultPluginOutput;
 
+export type BrowserMessage = {
+  text: string;
+  type: string;
+  error?: Error;
+} & DefaultPluginOutput;
+
+export type PluginOutput = {
+  filmstrips?: Array<Filmstrip>;
+  networkinfo?: Array<NetworkInfo>;
+  browserconsole?: Array<BrowserMessage>;
+  traces?: Array<TraceOutput>;
+  metrics?: PerfMetrics;
+};
+
+export type ScreenshotOptions = 'on' | 'off' | 'only-on-failure';
+
 export type CliArgs = {
+  capability?: Array<string>;
   config?: string;
-  environment?: string;
   outfd?: number;
   headless?: boolean;
-  screenshots?: boolean;
+  screenshots?: ScreenshotOptions;
+  ssblocks?: boolean;
   metrics?: boolean;
   filmstrips?: boolean;
+  trace?: boolean;
   dryRun?: boolean;
-  journeyName?: string;
   network?: boolean;
   pauseOnError?: boolean;
+  quietExitCode?: boolean;
   reporter?: Reporters;
   wsEndpoint?: string;
   sandbox?: boolean;
-  json?: boolean;
   pattern?: string;
   inline: boolean;
-  require: string[];
+  match?: string;
+  tags?: Array<string>;
+  require: Array<string>;
   debug?: boolean;
-  suiteParams?: string;
+  ignoreHttpsErrors?: boolean;
+  params?: Params;
+  throttling?: boolean | string;
+  playwrightOptions?: LaunchOptions & BrowserContextOptions;
+  richEvents?: boolean;
+};
+
+export type PlaywrightOptions = LaunchOptions & BrowserContextOptions;
+export type SyntheticsConfig = {
+  params?: Params;
+  playwrightOptions?: PlaywrightOptions;
 };

package/src/config.ts

@@ -24,13 +24,10 @@
  */
 
 import { isAbsolute, resolve, dirname } from 'path';
+import { SyntheticsConfig } from './common_types';
 import { isFile } from './helpers';
 
-interface Config {
-  params?: Record<string, unknown>;
-}
-
-export function readConfig(env: string, config?: string): Config {
+export function readConfig(env: string, config?: string): SyntheticsConfig {
   let options = {};
   const cwd = process.cwd();
   /**

package/src/core/expect.ts

@@ -0,0 +1,187 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2020-present, Elastic NV
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+import expectLib from 'expect';
+import type {
+  AsymmetricMatcher,
+  MatcherState,
+  ExpectedAssertionsErrors,
+} from 'expect/build/types';
+
+// Copied source code from expect/build/types.d.ts
+export declare type Expect = {
+  <T = unknown>(actual: T): synthetics.Matchers<T>;
+  assertions(arg0: number): void;
+  extend(arg0: any): void;
+  extractExpectedAssertionsErrors: () => ExpectedAssertionsErrors;
+  getState(): MatcherState;
+  hasAssertions(): void;
+  setState(state: Partial<MatcherState>): void;
+  any(expectedObject: any): AsymmetricMatcher;
+  anything(): AsymmetricMatcher;
+  arrayContaining(sample: Array<unknown>): AsymmetricMatcher;
+  objectContaining(sample: Record<string, unknown>): AsymmetricMatcher;
+  stringContaining(expected: string): AsymmetricMatcher;
+  stringMatching(expected: string | RegExp): AsymmetricMatcher;
+};
+
+/**
+ * Override matchers from expect in our synthetic namespace to
+ * reduce support for spy and snapshot matchers which is
+ * impelemed via jest matchers
+ *
+ * We declare the types in global synthetics namespace which allows
+ * users to extend expect functionality without type errors
+ */
+declare global {
+  export namespace synthetics {
+    export interface Matchers<R> {
+      /**
+       * If you know how to test something, `.not` lets you test its opposite.
+       */
+      not: Matchers<R>;
+      /**
+       * 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>>;
+      /**
+       * 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>>;
+      /**
+       * 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;
+      /**
+       * 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;
+      /**
+       * Ensure that a variable is not undefined.
+       */
+      toBeDefined(): R;
+      /**
+       * When you don't care what a value is, you just want to
+       * ensure a value is false in a boolean context.
+       */
+      toBeFalsy(): R;
+      /**
+       * For comparing floating point numbers.
+       */
+      toBeGreaterThan(expected: number | bigint): R;
+      /**
+       * For comparing floating point numbers.
+       */
+      toBeGreaterThanOrEqual(expected: number | bigint): R;
+      /**
+       * Ensure that an object is an instance of a class.
+       * This matcher uses `instanceof` underneath.
+       */
+      /* eslint-disable-next-line */
+      toBeInstanceOf(expected: Function): R;
+      /**
+       * For comparing floating point numbers.
+       */
+      toBeLessThan(expected: number | bigint): R;
+      /**
+       * For comparing floating point numbers.
+       */
+      toBeLessThanOrEqual(expected: number | bigint): R;
+      /**
+       * 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;
+      /**
+       * 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;
+      /**
+       * Used to check that a variable is undefined.
+       */
+      toBeUndefined(): R;
+      /**
+       * Used to check that a variable is NaN.
+       */
+      toBeNaN(): R;
+      /**
+       * 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;
+      /**
+       * 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;
+      /**
+       * 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;
+      /**
+       * Used to check that an object has a `.length` property
+       * and it is set to a certain numeric value.
+       */
+      toHaveLength(expected: number): R;
+      /**
+       * 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
+       * the keyPath for deep references.
+       *
+       * Optionally, you can provide a value to check if it's equal to the value present at keyPath
+       * on the target object. This matcher uses 'deep equality' (like `toEqual()`) and recursively checks
+       * the equality of all fields.
+       *
+       * @example
+       *
+       * expect(houseForSale).toHaveProperty('kitchen.area', 20);
+       */
+      toHaveProperty(keyPath: string | Array<string>, value?: unknown): R;
+      /**
+       * Check that a string matches a regular expression.
+       */
+      toMatch(expected: string | RegExp): R;
+      /**
+       * Used to check that a JavaScript object matches a subset of the properties of an object
+       */
+      toMatchObject(expected: Record<string, unknown> | Array<unknown>): R;
+      /**
+       * Use to test that objects have the same types as well as structure.
+       */
+      toStrictEqual(expected: unknown): R;
+    }
+  }
+}
+
+export const expect: Expect = expectLib;