feat(testlab): add a new helper deserializedFromJson

Implement a helper function to convert an object (e.g. a Model instance)
to a data object representing JSON version of the input object.
Specifically, properties set to a value that cannot be represented in
JSON (e.g. `undefined`) are removed from the result.

Author: bajtos

packages/testlab/README.md

@@ -53,6 +53,7 @@ Table of contents:
 - [givenHttpServerConfig](#givenhttpserverconfig) - Generate HTTP server config.
 - [httpGetAsync](#httpgetasync) - Async wrapper for HTTP GET requests.
 - [httpsGetAsync](#httpsgetasync) - Async wrapper for HTTPS GET requests.
+- [toJSON](#toJSON) - A helper to obtain JSON data representing a given object.
 
 ### `expect`
 
@@ -134,6 +135,24 @@ import {httpsGetAsync} from '@loopback/testlab';
 const response = await httpsGetAsync('https://example.com');
 ```
 
+### `toJSON`
+
+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.
+
+```ts
+import {createClientForHandler, toJSON} from '@loopback/testlab';
+
+it('gets a todo by ID', () => {
+  return client
+    .get(`/todos/${persistedTodo.id}`)
+    .expect(200, toJSON(persistedTodo));
+});
+```
+
 #### Test request parsing
 
 Use the factory function `stubServerRequest` to create a stub request that can

packages/testlab/src/index.ts

@@ -12,3 +12,4 @@ export * from './test-sandbox';
 export * from './skip-travis';
 export * from './request';
 export * from './http-server-config';
+export * from './to-json';

packages/testlab/src/to-json.ts

@@ -0,0 +1,39 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/testlab
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// 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.
+
+// tslint:disable-next-line:unified-signatures
+export function toJSON(value: undefined): undefined;
+export function toJSON(value: null): null;
+export function toJSON(value: number): number;
+export function toJSON(value: boolean): boolean;
+// tslint:disable-next-line:unified-signatures
+export function toJSON(value: string): string;
+
+export function toJSON<T>(value: T) {
+  return JSON.parse(JSON.stringify({value})).value;
+}

packages/testlab/test/unit/to-json.test.ts

@@ -0,0 +1,159 @@
+// Copyright IBM Corp. 2018. 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 {expect} from '../../src/expect';
+import {toJSON} from '../../src/to-json';
+
+describe('toJSON', () => {
+  it('removes properties set to undefined', () => {
+    const value = toJSON({
+      title: 'a-todo-title',
+      isComplete: undefined,
+    });
+    expectObjectValue(value, {
+      title: 'a-todo-title',
+    });
+  });
+
+  it('handles null', () => {
+    const value = toJSON(null);
+    expectNull(value);
+  });
+
+  it('handles undefined', () => {
+    const value = toJSON(undefined);
+    expectUndefined(value);
+  });
+
+  it('handles numbers', () => {
+    const value = toJSON(123);
+    expectNumericValue(value, 123);
+  });
+
+  it('handles strings', () => {
+    const value = toJSON('text');
+    expectStringValue(value, 'text');
+  });
+
+  it('handles booleans', () => {
+    const value = toJSON(true);
+    expectBooleanValue(value, true);
+  });
+
+  it('handles dates', () => {
+    const value = toJSON(new Date('2018-01-01T00:00:00.000Z'));
+    expectStringValue(value, '2018-01-01T00:00:00.000Z');
+  });
+
+  it('handles top-level arrays', () => {
+    const value = toJSON([1, 'text']);
+    expectArrayValue(value, [1, 'text']);
+  });
+
+  it('handles nested array', () => {
+    const value = toJSON({items: ['pen', 'pencil']});
+    expectObjectValue(value, {items: ['pen', 'pencil']});
+  });
+
+  it('handles functions', () => {
+    const value = toJSON(function foo() {});
+    expectUndefined(value);
+  });
+
+  it('handles classes with custom toJSON', () => {
+    class Customer {
+      // tslint:disable-next-line:no-unused-variable
+      private __data: object;
+
+      constructor(public id: string, public email: string) {
+        this.__data = {id, email};
+      }
+
+      toJSON() {
+        return {id: this.id, email: this.email};
+      }
+    }
+
+    const value = toJSON(new Customer('an-id', 'test@example.com'));
+    expectObjectValue(value, {id: 'an-id', email: 'test@example.com'});
+    expect(value.constructor).to.equal(Object);
+  });
+
+  it('handles nested class instance with custom toJSON', () => {
+    class Address {
+      constructor(public street: string, public city: string) {}
+
+      toJSON() {
+        return {
+          model: 'Address',
+          street: this.street,
+          city: this.city,
+        };
+      }
+    }
+
+    class Customer {
+      constructor(public email: string, public address: Address) {}
+
+      toJSON() {
+        return {
+          model: 'Customer',
+          email: this.email,
+          address: this.address,
+        };
+      }
+    }
+
+    const value = toJSON(
+      new Customer(
+        'test@example.com',
+        new Address('10 Downing Street', 'London'),
+      ),
+    );
+
+    expectObjectValue(value, {
+      model: 'Customer',
+      email: 'test@example.com',
+      address: {
+        model: 'Address',
+        street: '10 Downing Street',
+        city: 'London',
+      },
+    });
+
+    expect(value.constructor).to.equal(Object);
+    expect((value as Customer).address.constructor).to.equal(Object);
+  });
+});
+
+// Helpers to enforce compile-time type checks
+
+function expectStringValue(actual: string, expected: string) {
+  expect(actual).to.equal(expected);
+}
+
+function expectNumericValue(actual: number, expected: number) {
+  expect(actual).to.equal(expected);
+}
+
+function expectBooleanValue(actual: boolean, expected: boolean) {
+  expect(actual).to.equal(expected);
+}
+
+function expectObjectValue(actual: object, expected: object) {
+  expect(actual).to.deepEqual(expected);
+}
+
+function expectArrayValue<T>(actual: T[], expected: T[]) {
+  expect(actual).to.deepEqual(expected);
+}
+
+function expectNull(actual: null) {
+  expect(actual).to.be.null();
+}
+
+function expectUndefined(actual: undefined) {
+  expect(actual).to.be.undefined();
+}