@loopback/testlab 4.0.0-alpha.7 → 4.0.1

package/src/request.ts

@@ -0,0 +1,45 @@
+// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import http, {IncomingMessage} from 'http';
+import https from 'https';
+import url from 'url';
+
+/**
+ * Async wrapper for making HTTP GET requests
+ * @param urlString
+ */
+export function httpGetAsync(
+  urlString: string,
+  agent?: http.Agent,
+): Promise<IncomingMessage> {
+  return new Promise((resolve, reject) => {
+    const urlOptions = url.parse(urlString);
+    const options = {agent, ...urlOptions};
+    http.get(options, resolve).on('error', reject);
+  });
+}
+
+/**
+ * Async wrapper for making HTTPS GET requests
+ * @param urlString
+ */
+export function httpsGetAsync(
+  urlString: string,
+  agent?: https.Agent,
+): Promise<IncomingMessage> {
+  agent =
+    agent ??
+    new https.Agent({
+      rejectUnauthorized: false,
+    });
+
+  const urlOptions = url.parse(urlString);
+  const options = {agent, ...urlOptions};
+
+  return new Promise((resolve, reject) => {
+    https.get(options, resolve).on('error', reject);
+  });
+}

package/src/shot.ts

@@ -0,0 +1,191 @@
+// Copyright IBM Corp. 2017,2019. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/*
+ * HTTP Request/Response mocks
+ * https://github.com/hapijs/shot
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import express from 'express';
+import {IncomingMessage, ServerResponse} from 'http';
+import {
+  Listener as ShotListener,
+  RequestOptions as ShotRequestOptions,
+  ResponseObject,
+} from 'shot'; // <-- workaround for missing type-defs for @hapi/shot
+import util from 'util';
+
+const inject: (
+  dispatchFunc: ShotListener,
+  options: ShotRequestOptions,
+) => Promise<ResponseObject> = require('@hapi/shot');
+// ^^ workaround for missing type-defs for @hapi/shot
+
+export {inject, ShotRequestOptions};
+
+const ShotRequest: ShotRequestCtor = require('@hapi/shot/lib/request');
+type ShotRequestCtor = new (options: ShotRequestOptions) => IncomingMessage;
+
+export function stubServerRequest(
+  options: ShotRequestOptions,
+): IncomingMessage {
+  const stub = new ShotRequest(options);
+  // Hacky workaround for Express, see
+  // https://github.com/expressjs/express/blob/4.16.3/lib/middleware/init.js
+  // https://github.com/hapijs/shot/issues/82#issuecomment-247943773
+  // https://github.com/jfhbrook/pickleback
+  Object.assign(stub, ShotRequest.prototype);
+  return stub;
+}
+
+const ShotResponse: ShotResponseCtor = require('@hapi/shot/lib/response');
+export type ShotCallback = (response: ResponseObject) => void;
+
+export type ShotResponseCtor = new (
+  request: IncomingMessage,
+  onEnd: ShotCallback,
+) => ServerResponse;
+
+export function stubServerResponse(
+  request: IncomingMessage,
+  onEnd: ShotCallback,
+): ServerResponse {
+  const stub = new ShotResponse(request, onEnd);
+  // Hacky workaround for Express, see
+  // https://github.com/expressjs/express/blob/4.16.3/lib/middleware/init.js
+  // https://github.com/hapijs/shot/issues/82#issuecomment-247943773
+  // https://github.com/jfhbrook/pickleback
+  Object.assign(stub, ShotResponse.prototype);
+  return stub;
+}
+
+export type ObservedResponse = ResponseObject;
+
+export interface HandlerContextStub {
+  request: IncomingMessage;
+  response: ServerResponse;
+  result: Promise<ObservedResponse>;
+}
+
+export function stubHandlerContext(
+  requestOptions: ShotRequestOptions = {url: '/'},
+): HandlerContextStub {
+  const request = stubServerRequest(requestOptions);
+  let response: ServerResponse | undefined;
+  const result = new Promise<ObservedResponse>(resolve => {
+    response = new ShotResponse(request, resolve);
+  });
+
+  const context = {request, response: response!, result};
+  defineCustomContextInspect(context, requestOptions);
+  return context;
+}
+
+export interface ExpressContextStub extends HandlerContextStub {
+  app: express.Application;
+  request: express.Request;
+  response: express.Response;
+  result: Promise<ObservedResponse>;
+}
+
+export function stubExpressContext(
+  requestOptions: ShotRequestOptions = {url: '/'},
+): ExpressContextStub {
+  const app = express();
+
+  const request = new ShotRequest(requestOptions) as express.Request;
+  // mix in Express Request API
+  const RequestApi = (express as any).request;
+  for (const key of Object.getOwnPropertyNames(RequestApi)) {
+    Object.defineProperty(
+      request,
+      key,
+      Object.getOwnPropertyDescriptor(RequestApi, key)!,
+    );
+  }
+  request.app = app;
+  request.originalUrl = request.url;
+  parseQuery(request);
+
+  let response: express.Response | undefined;
+  const result = new Promise<ObservedResponse>(resolve => {
+    response = new ShotResponse(request, resolve) as express.Response;
+    // mix in Express Response API
+    Object.assign(response, (express as any).response);
+    const ResponseApi = (express as any).response;
+    for (const key of Object.getOwnPropertyNames(ResponseApi)) {
+      Object.defineProperty(
+        response,
+        key,
+        Object.getOwnPropertyDescriptor(ResponseApi, key)!,
+      );
+    }
+    response.app = app;
+    (response as any).req = request;
+    (request as any).res = response;
+  });
+
+  const context = {app, request, response: response!, result};
+  defineCustomContextInspect(context, requestOptions);
+  return context;
+}
+
+/**
+ * Use `express.query` to parse the query string into `request.query` object
+ * @param request - Express http request object
+ */
+function parseQuery(request: express.Request) {
+  // Use `express.query` to parse the query string
+  // See https://github.com/expressjs/express/blob/master/lib/express.js#L79
+  // See https://github.com/expressjs/express/blob/master/lib/middleware/query.js
+  (express as any).query()(request, {}, () => {});
+}
+
+function defineCustomContextInspect(
+  context: HandlerContextStub,
+  requestOptions: ShotRequestOptions,
+) {
+  // Setup custom inspect functions to make test error messages easier to read
+  const inspectOpts = (depth: number, opts: any) =>
+    util.inspect(requestOptions, opts);
+
+  defineCustomInspect(
+    context.request,
+    (depth, opts) => `[RequestStub with options ${inspectOpts(depth, opts)}]`,
+  );
+
+  defineCustomInspect(
+    context.response,
+    (depth, opts) =>
+      `[ResponseStub for request with options ${inspectOpts(depth, opts)}]`,
+  );
+
+  context.result = context.result.then(r => {
+    defineCustomInspect(
+      r,
+      (depth, opts) =>
+        `[ObservedResponse for request with options ${inspectOpts(
+          depth,
+          opts,
+        )}]`,
+    );
+    return r;
+  });
+}
+
+// @types/node@v10.17.29 seems to miss the type definition of `util.inspect.custom`
+// error TS2339: Property 'custom' does not exist on type 'typeof inspect'.
+// Use a workaround for now to access the `custom` symbol for now.
+// https://nodejs.org/api/util.html#util_util_inspect_custom
+const custom = Symbol.for('nodejs.util.inspect.custom');
+
+function defineCustomInspect(
+  obj: any,
+  inspectFn: (depth: number, opts: any) => {},
+) {
+  obj[custom] = inspectFn;
+}

package/src/sinon.ts

@@ -0,0 +1,38 @@
+// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import sinon, {SinonSpy} from 'sinon';
+
+export {sinon, SinonSpy};
+
+export type StubbedInstanceWithSinonAccessor<T> = T & {
+  stubs: sinon.SinonStubbedInstance<T>;
+};
+
+/**
+ * Creates a new object with the given functions as the prototype and stubs all
+ * implemented functions.
+ *
+ * Note: The given constructor function is not invoked. See also the stub API.
+ *
+ * This is a helper method replacing `sinon.createStubInstance` and working
+ * around the limitations of TypeScript and Sinon, where Sinon is not able to
+ * list private/protected members in the type definition of the stub instance
+ * and therefore the stub instance cannot be assigned to places expecting TType.
+ * See also
+ *  - https://github.com/Microsoft/TypeScript/issues/13543
+ *  - https://github.com/DefinitelyTyped/DefinitelyTyped/issues/14811
+ *
+ * @typeParam TType - Type being stubbed.
+ * @param constructor - Object or class to stub.
+ * @returns A stubbed version of the constructor, with an extra property `stubs`
+ * providing access to stub API for individual methods.
+ */
+export function createStubInstance<TType>(
+  constructor: sinon.StubbableType<TType>,
+): StubbedInstanceWithSinonAccessor<TType> {
+  const stub = sinon.createStubInstance(constructor);
+  return Object.assign(stub as TType, {stubs: stub});
+}

package/src/skip.ts

@@ -0,0 +1,76 @@
+// Copyright IBM Corp. 2019,2020. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/**
+ * A function defining a new test case or a test suite, e.g. `it` or `describe`.
+ */
+export type TestDefinition<ARGS extends unknown[], RETVAL> = (
+  name: string,
+  ...args: ARGS
+) => RETVAL;
+
+/**
+ * Helper function for skipping tests when a certain condition is met.
+ *
+ * @example
+ * ```ts
+ * skipIf(
+ *   !features.freeFormProperties,
+ *   describe,
+ *  'free-form properties (strict: false)',
+ *   () => {
+ *     // the tests
+ *   }
+ * );
+ * ```
+ *
+ * @param skip - Should the test case/suite be skipped?
+ * @param verb - The function to invoke to define the test case or the test
+ * suite, e.g. `it` or `describe`.
+ * @param name - The test name (the first argument of `verb` function).
+ * @param args - Additional arguments (framework specific), typically a function
+ * implementing the test.
+ */
+export function skipIf<ARGS extends unknown[], RETVAL>(
+  skip: boolean,
+  verb: TestDefinition<ARGS, RETVAL> & {skip: TestDefinition<ARGS, RETVAL>},
+  name: string,
+  ...args: ARGS
+): RETVAL {
+  if (skip) {
+    return verb.skip(`[SKIPPED] ${name}`, ...args);
+  } else {
+    return verb(name, ...args);
+  }
+}
+
+/**
+ * Helper function for skipping tests on Travis CI.
+ *
+ * @example
+ *
+ * ```ts
+ * skipOnTravis(it, 'does something when some condition', async () => {
+ *   // the test
+ * });
+ * ```
+ *
+ * @param verb - The function to invoke to define the test case or the test
+ * suite, e.g. `it` or `describe`.
+ * @param name - The test name (the first argument of `verb` function).
+ * @param args - Additional arguments (framework specific), typically a function
+ * implementing the test.
+ */
+export function skipOnTravis<ARGS extends unknown[], RETVAL>(
+  verb: TestDefinition<ARGS, RETVAL> & {skip: TestDefinition<ARGS, RETVAL>},
+  name: string,
+  ...args: ARGS
+): RETVAL {
+  if (process.env.TRAVIS) {
+    return verb.skip(`[SKIPPED ON TRAVIS] ${name}`, ...args);
+  } else {
+    return verb(name, ...args);
+  }
+}

package/src/test-sandbox.ts

@@ -0,0 +1,181 @@
+// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {
+  appendFile,
+  copy,
+  emptyDir,
+  ensureDir,
+  ensureDirSync,
+  mkdtempSync,
+  outputFile,
+  outputJson,
+  pathExists,
+  readFile,
+  remove,
+} from 'fs-extra';
+import {join, parse, resolve} from 'path';
+
+/**
+ * Options for a test sandbox
+ */
+export interface TestSandboxOptions {
+  /**
+   * The `subdir` controls if/how the sandbox creates a subdirectory under the
+   * root path. It has one of the following values:
+   *
+   * - `true`: Creates a unique subdirectory. This will be the default behavior.
+   * - `false`: Uses the root path as the target directory without creating a
+   * subdirectory.
+   * - a string such as `sub-dir-1`: creates a subdirectory with the given value.
+   */
+  subdir: boolean | string;
+}
+
+/**
+ * TestSandbox class provides a convenient way to get a reference to a
+ * sandbox folder in which you can perform operations for testing purposes.
+ */
+export class TestSandbox {
+  // Path of the TestSandbox
+  private _path?: string;
+
+  public get path(): string {
+    if (!this._path) {
+      throw new Error(
+        `TestSandbox instance was deleted. Create a new instance.`,
+      );
+    }
+    return this._path;
+  }
+
+  /**
+   * Will create a directory if it doesn't already exist. If it exists, you
+   * still get an instance of the TestSandbox.
+   *
+   * @example
+   * ```ts
+   * // Create a sandbox as a unique temporary subdirectory under the rootPath
+   * const sandbox = new TestSandbox(rootPath);
+   * const sandbox = new TestSandbox(rootPath, {subdir: true});
+   *
+   * // Create a sandbox in the root path directly
+   * // This is same as the old behavior
+   * const sandbox = new TestSandbox(rootPath, {subdir: false});
+   *
+   * // Create a sandbox in the `test1` subdirectory of the root path
+   * const sandbox = new TestSandbox(rootPath, {subdir: 'test1'});
+   * ```
+   *
+   * @param rootPath - Root path of the TestSandbox. If relative it will be
+   * resolved against the current directory.
+   * @param options - Options to control if/how the sandbox creates a
+   * subdirectory for the sandbox. If not provided, the sandbox
+   * will automatically creates a unique temporary subdirectory. This allows
+   * sandboxes with the same root path can be used in parallel during testing.
+   */
+  constructor(rootPath: string, options?: TestSandboxOptions) {
+    rootPath = resolve(rootPath);
+    ensureDirSync(rootPath);
+    options = {subdir: true, ...options};
+    const subdir = typeof options.subdir === 'string' ? options.subdir : '.';
+    if (options.subdir !== true) {
+      this._path = resolve(rootPath, subdir);
+    } else {
+      // Create a unique temporary directory under the root path
+      // See https://nodejs.org/api/fs.html#fs_fs_mkdtempsync_prefix_options
+      this._path = mkdtempSync(join(rootPath, `/${process.pid}`));
+    }
+  }
+
+  /**
+   * Resets the TestSandbox. (Remove all files in it).
+   */
+  async reset(): Promise<void> {
+    // Decache files from require's cache so future tests aren't affected incase
+    // a file is recreated in sandbox with the same file name but different
+    // contents after resetting the sandbox.
+    for (const key in require.cache) {
+      if (key.startsWith(this.path)) {
+        delete require.cache[key];
+      }
+    }
+
+    await emptyDir(this.path);
+  }
+
+  /**
+   * Deletes the TestSandbox.
+   */
+  async delete(): Promise<void> {
+    await remove(this.path);
+    delete this._path;
+  }
+
+  /**
+   * Makes a directory in the TestSandbox
+   *
+   * @param dir - Name of directory to create (relative to TestSandbox path)
+   */
+  async mkdir(dir: string): Promise<void> {
+    await ensureDir(resolve(this.path, dir));
+  }
+
+  /**
+   * Copies a file from src to the TestSandbox. If copying a `.js` file which
+   * has an accompanying `.js.map` file in the src file location, the dest file
+   * will have its sourceMappingURL updated to point to the original file as
+   * an absolute path so you don't need to copy the map file.
+   *
+   * @param src - Absolute path of file to be copied to the TestSandbox
+   * @param dest - Optional. Destination filename of the copy operation
+   * (relative to TestSandbox). Original filename used if not specified.
+   * @param transform - Optional. A function to transform the file content.
+   */
+  async copyFile(
+    src: string,
+    dest?: string,
+    transform?: (content: string) => string,
+  ): Promise<void> {
+    dest = dest
+      ? resolve(this.path, dest)
+      : resolve(this.path, parse(src).base);
+
+    if (transform == null) {
+      await copy(src, dest);
+    } else {
+      let content = await readFile(src, 'utf-8');
+      content = transform(content);
+      await outputFile(dest, content, {encoding: 'utf-8'});
+    }
+
+    if (parse(src).ext === '.js' && (await pathExists(src + '.map'))) {
+      const srcMap = src + '.map';
+      await appendFile(dest, `\n//# sourceMappingURL=${srcMap}`);
+    }
+  }
+
+  /**
+   * Creates a new file and writes the given data serialized as JSON.
+   *
+   * @param dest - Destination filename, optionally including a relative path.
+   * @param data - The data to write.
+   */
+  async writeJsonFile(dest: string, data: unknown): Promise<void> {
+    dest = resolve(this.path, dest);
+    return outputJson(dest, data, {spaces: 2});
+  }
+
+  /**
+   * Creates a new file and writes the given data as a UTF-8-encoded text.
+   *
+   * @param dest - Destination filename, optionally including a relative path.
+   * @param data - The text to write.
+   */
+  async writeTextFile(dest: string, data: string): Promise<void> {
+    dest = resolve(this.path, dest);
+    return outputFile(dest, data, 'utf-8');
+  }
+}

package/src/to-json.ts

@@ -0,0 +1,54 @@
+// Copyright IBM Corp. 2018,2019. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/* eslint-disable @typescript-eslint/unified-signatures */
+
+// Important! Date.prototype.toJSON() returns a string.
+export function toJSON(value: Date): string;
+
+// Important! Functions cannot be encoded in JSON.
+export function toJSON(value: Function): undefined;
+
+// Distinguish arrays from objects (an array is an object too)
+export function toJSON(value: unknown[]): unknown[];
+
+/**
+ * JSON encoding does not preserve properties that are undefined
+ * As a result, deepEqual checks fail because the expected model
+ * value contains these undefined property values, while the actual
+ * result returned by REST API does not.
+ * Use this function to convert a model instance into a data object
+ * as returned by REST API
+ */
+export function toJSON(value: object): object;
+
+// The following overloads are provided for convenience.
+// In practice, they should not be necessary, as they simply return the input
+// value without any modifications.
+
+export function toJSON(value: undefined): undefined;
+export function toJSON(value: null): null;
+export function toJSON(value: number): number;
+export function toJSON(value: boolean): boolean;
+export function toJSON(value: string): string;
+
+// The following overloads are required to allow TypesScript handle
+// commonly used union types.
+
+export function toJSON(value: unknown[] | null): unknown[] | null;
+export function toJSON(value: unknown[] | undefined): unknown[] | undefined;
+export function toJSON(
+  value: unknown[] | null | undefined,
+): unknown[] | null | undefined;
+
+export function toJSON(value: object | null): object | null;
+export function toJSON(value: object | undefined): object | undefined;
+export function toJSON(
+  value: object | null | undefined,
+): object | null | undefined;
+
+export function toJSON<T>(value: T) {
+  return JSON.parse(JSON.stringify({value})).value;
+}

package/src/validate-api-spec.ts

@@ -0,0 +1,14 @@
+// Copyright IBM Corp. 2017,2019. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+const validator = require('oas-validator');
+import {promisify} from 'util';
+
+const validateAsync = promisify(validator.validate);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function validateApiSpec(spec: any): Promise<void> {
+  await validateAsync(spec, {});
+}

package/index.d.ts

@@ -1,6 +0,0 @@
-// Copyright IBM Corp. 2013,2017. All Rights Reserved.
-// Node module: @loopback/testlab
-// This file is licensed under the MIT License.
-// License text available at https://opensource.org/licenses/MIT
-
-export * from './lib/testlab';

package/index.js

@@ -1,9 +0,0 @@
-// Copyright IBM Corp. 2013,2017. All Rights Reserved.
-// Node module: @loopback/testlab
-// This file is licensed under the MIT License.
-// License text available at https://opensource.org/licenses/MIT
-
-const nodeMajorVersion = +process.versions.node.split('.')[0];
-module.exports = nodeMajorVersion >= 7 ?
-  require('./lib/testlab') :
-  require('./lib6/testlab');

package/lib/client.d.ts

@@ -1,23 +0,0 @@
-/// <reference types="supertest" />
-/// <reference types="node" />
-import * as http from 'http';
-import supertest = require('supertest');
-export { supertest };
-export declare type Client = supertest.SuperTest<supertest.Test>;
-/**
- * Create a SuperTest client connected to an HTTP server listening
- * on an ephemeral port and calling `handler` to handle incoming requests.
- * @param handler
- */
-export declare function createClientForHandler(handler: (req: http.ServerRequest, res: http.ServerResponse) => void): Client;
-export interface Server {
-    config: {
-        port: number;
-    };
-    start(): Promise<void>;
-}
-export declare function createClientForServer(server: Server): Promise<Client>;
-export interface Application {
-    handleHttp(req: http.ServerRequest, res: http.ServerResponse): void;
-}
-export declare function createClientForApp(app: Application): Client;

package/lib/client.js

@@ -1,34 +0,0 @@
-"use strict";
-// Copyright IBM Corp. 2013,2017. All Rights Reserved.
-// Node module: @loopback/testlab
-// This file is licensed under the MIT License.
-// License text available at https://opensource.org/licenses/MIT
-Object.defineProperty(exports, "__esModule", { value: true });
-/*
- * HTTP client utilities
- */
-const http = require("http");
-const supertest = require("supertest");
-exports.supertest = supertest;
-/**
- * Create a SuperTest client connected to an HTTP server listening
- * on an ephemeral port and calling `handler` to handle incoming requests.
- * @param handler
- */
-function createClientForHandler(handler) {
-    const server = http.createServer(handler);
-    return supertest(server);
-}
-exports.createClientForHandler = createClientForHandler;
-async function createClientForServer(server) {
-    await server.start();
-    const url = `http://127.0.0.1:${server.config.port}`;
-    // TODO(bajtos) Find a way how to stop the server after all tests are done
-    return supertest(url);
-}
-exports.createClientForServer = createClientForServer;
-function createClientForApp(app) {
-    return createClientForHandler(app.handleHttp);
-}
-exports.createClientForApp = createClientForApp;
-//# sourceMappingURL=client.js.map

package/lib/client.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,iCAAiC;AACjC,+CAA+C;AAC/C,gEAAgE;;AAEhE;;GAEG;AAEH,6BAA6B;AAC7B,uCAAwC;AAEhC,8BAAS;AAIjB;;;;GAIG;AACH,gCACE,OAAoE;IAEpE,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AALD,wDAKC;AAOM,KAAK,gCAAgC,MAAc;IACxD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,MAAM,GAAG,GAAG,oBAAoB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrD,0EAA0E;IAC1E,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AALD,sDAKC;AAMD,4BAAmC,GAAgB;IACjD,MAAM,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAChD,CAAC;AAFD,gDAEC"}