Merge pull request #180 from apiaryio/179-real-coercion

fix: uses strict and weak coercion for real and expected messages

Author: artem-zakharchenko

lib/next/test/integration/validateMessage.test.js

@@ -361,4 +361,104 @@ describe('validateMessage', () => {
       });
     });
   });
+
+  describe('with non-matching headers', () => {
+    const result = validateMessage(
+      {
+        statusCode: 404
+      },
+      {
+        statusCode: 404,
+        headers: {
+          'Content-Type': 'text/plain'
+        }
+      }
+    );
+
+    it('returns validation result object', () => {
+      assert.isObject(result);
+    });
+
+    it('contains all validatable keys', () => {
+      assert.hasAllDeepKeys(result, ['isValid', 'statusCode', 'headers']);
+    });
+
+    it('has "isValid" as false', () => {
+      assert.propertyVal(result, 'isValid', false);
+    });
+
+    describe('statusCode', () => {
+      it('has "TextDiff" validator', () => {
+        assert.propertyVal(result.statusCode, 'validator', 'TextDiff');
+      });
+
+      it('has "text/vnd.apiary.status-code" real type', () => {
+        assert.propertyVal(
+          result.statusCode,
+          'realType',
+          'text/vnd.apiary.status-code'
+        );
+      });
+
+      it('has "text/vnd.apiary.status-code" expected type', () => {
+        assert.propertyVal(
+          result.statusCode,
+          'expectedType',
+          'text/vnd.apiary.status-code'
+        );
+      });
+
+      it('has no errors', () => {
+        assert.lengthOf(result.statusCode.results, 0);
+      });
+    });
+
+    describe('headers', () => {
+      it('has "HeadersJsonExample" validator', () => {
+        assert.propertyVal(result.headers, 'validator', 'HeadersJsonExample');
+      });
+
+      it('has "application/vnd.apiary.http-headers+json" real type', () => {
+        assert.propertyVal(
+          result.headers,
+          'realType',
+          'application/vnd.apiary.http-headers+json'
+        );
+      });
+
+      it('has "application/vnd.apiary.http-headers+json" expected type', () => {
+        assert.propertyVal(
+          result.headers,
+          'expectedType',
+          'application/vnd.apiary.http-headers+json'
+        );
+      });
+
+      describe('produces an error', () => {
+        it('exactly one error', () => {
+          assert.lengthOf(result.headers.results, 1);
+        });
+
+        it('has "error" severity', () => {
+          assert.propertyVal(result.headers.results[0], 'severity', 'error');
+        });
+
+        it('has pointer to missing "Content-Type"', () => {
+          assert.propertyVal(
+            result.headers.results[0],
+            'pointer',
+            '/content-type'
+          );
+        });
+
+        it('has explanatory message', () => {
+          assert.propertyVal(
+            result.headers.results[0],
+            'message',
+            `At '/content-type' Missing required property: content-type`
+          );
+        });
+      });
+    });
+  });
 });

lib/next/test/unit/units/normalize/normalizeHeaders.test.js

@@ -5,10 +5,8 @@ const {
 
 describe('normalizeHeaders', () => {
   describe('when given nothing', () => {
-    const headers = normalizeHeaders(undefined);
-
-    it('coerces to empty object', () => {
-      assert.deepEqual(headers, {});
+    it('throws upon invalid headers value', () => {
+      assert.throw(() => normalizeHeaders(undefined));
     });
   });
 

lib/next/test/unit/utils/evolve.test.js

@@ -11,71 +11,108 @@ const unexpectedTypes = [
 ];
 
 describe('evolve', () => {
-  describe('evolves a given object', () => {
-    const res = evolve({
-      a: multiply(2),
-      c: () => null
-    })({
-      a: 2,
-      b: 'foo'
-    });
+  describe('weak mode', () => {
+    describe('evolves given object', () => {
+      const result = evolve({
+        a: multiply(2),
+        c: () => null
+      })({
+        a: 2,
+        b: 'foo'
+      });
 
-    it('returns object', () => {
-      assert.isObject(res);
-    });
+      it('returns object', () => {
+        assert.isObject(result);
+      });
 
-    it('evolves matching properties', () => {
-      assert.propertyVal(res, 'a', 4);
-    });
+      it('evolves matching properties', () => {
+        assert.propertyVal(result, 'a', 4);
+      });
 
-    it('bypasses properties not in schema', () => {
-      assert.propertyVal(res, 'b', 'foo');
-    });
+      it('bypasses properties not in schema', () => {
+        assert.propertyVal(result, 'b', 'foo');
+      });
 
-    it('ignores properties not in data', () => {
-      assert.notProperty(res, 'c');
+      it('ignores properties not in data', () => {
+        assert.notProperty(result, 'c');
+      });
     });
-  });
 
-  describe('evolves a given array', () => {
-    const res = evolve({
-      0: multiply(2),
-      1: multiply(3),
-      3: multiply(4)
-    })([1, 2, 3]);
+    describe('evolves given array', () => {
+      const result = evolve({
+        0: multiply(2),
+        1: multiply(3),
+        3: multiply(4)
+      })([1, 2, 3]);
 
-    it('returns array', () => {
-      assert.isArray(res);
-    });
+      it('returns array', () => {
+        assert.isArray(result);
+      });
 
-    it('evolves matching keys', () => {
-      assert.propertyVal(res, 0, 2);
-      assert.propertyVal(res, 1, 6);
-    });
+      it('evolves matching properties', () => {
+        assert.propertyVal(result, 0, 2);
+        assert.propertyVal(result, 1, 6);
+      });
 
-    it('bypasses keys not in schema', () => {
-      assert.propertyVal(res, 2, 3);
+      it('bypasses properties not in schema', () => {
+        assert.propertyVal(result, 2, 3);
+      });
+
+      it('ignores properties not in data', () => {
+        assert.notProperty(result, 3);
+      });
     });
 
-    it('ignores properties not in data', () => {
-      assert.notProperty(res, 3);
+    describe('throws when given unexpected schema', () => {
+      unexpectedTypes
+        .concat([['array', [1, 2]]])
+        .forEach(([typeName, dataType]) => {
+          it(`when given ${typeName}`, () => {
+            assert.throw(() => evolve(dataType)({}));
+          });
+        });
     });
-  });
 
-  describe('throws when given unexpected schema', () => {
-    unexpectedTypes
-      .concat([['array', [1, 2]]])
-      .forEach(([typeName, dataType]) => {
+    describe('throws when given unexpected data', () => {
+      unexpectedTypes.forEach(([typeName, dataType]) => {
         it(`when given ${typeName}`, () => {
-          assert.throw(() => evolve(dataType)({}));
+          assert.throw(() => evolve({ a: () => null })(dataType));
         });
       });
+    });
   });
 
-  describe('throws when given unexpected data', () => {
-    unexpectedTypes.forEach(([typeName, dataType]) => {
-      it(`when given ${typeName}`, () => {
-        assert.throw(() => evolve({ a: () => null })(dataType));
+  describe('strict mode', () => {
+    describe('evolves given object', () => {
+      const result = evolve(
+        {
+          method: () => 'GET',
+          headers: () => 'foo',
+          body: multiply(2)
+        },
+        {
+          strict: true
+        }
+      )({
+        statusCode: 200,
+        body: 5
+      });
+
+      it('returns an object', () => {
+        assert.isObject(result);
+      });
+
+      it('evolves matching properties', () => {
+        assert.propertyVal(result, 'body', 10);
+      });
+
+      it('forces all properties from schema', () => {
+        assert.propertyVal(result, 'headers', 'foo');
+        assert.propertyVal(result, 'method', 'GET');
+      });
+
+      it('bypasses properties not present in schema', () => {
+        assert.propertyVal(result, 'statusCode', 200);
       });
     });
   });

lib/next/units/coerce/coerceHeaders.js

@@ -0,0 +1,8 @@
+// Coerces given headers to an empty Object in case not present.
+// Conceptually, diff between missing headers and empty headers
+// should be treated the same.
+const coerceHeaders = (headers) => {
+  return headers || {};
+};
+
+module.exports = { coerceHeaders };

lib/next/units/coerce/index.js

@@ -0,0 +1,15 @@
+const evolve = require('../../utils/evolve');
+const { coerceHeaders } = require('./coerceHeaders');
+
+const coercionMap = {
+  headers: coerceHeaders
+};
+
+// Coercion uses strict evolve to ensure the properties
+// set in expected schema are set on the result object,
+// even if not present in data object. This is what
+// coercion is about, in the end.
+const coerce = evolve(coercionMap, { strict: true });
+const coerceWeak = evolve(coercionMap);
+
+module.exports = { coerce, coerceWeak };

lib/next/units/normalize/normalizeHeaders.js

@@ -8,10 +8,6 @@ const normalizeStringValue = (value) => {
  * @returns {Object}
  */
 const normalizeHeaders = (headers) => {
-  if (!headers) {
-    return {};
-  }
-
   const headersType = typeof headers;
   const isHeadersNull = headers == null;
 

lib/next/utils/evolve.js

@@ -2,11 +2,11 @@
  * Applies a given evolution schema to the given data Object.
  * Properties not present in schema are bypassed.
  * Properties not present in data are ignored.
- * @param {Object} schema
- * @param {Object|Array} data
- * @returns {Object}
+ * @param {Object<string, any>} schema
+ * @param {any[]|Object<string, any>} data
+ * @returns {any[]|Object<string, any>}
  */
-const evolve = (schema) => (data) => {
+const evolve = (schema, { strict = false } = {}) => (data) => {
   const dataType = typeof data;
   const schemaType = typeof schema;
   const isArray = Array.isArray(data);
@@ -24,10 +24,11 @@ const evolve = (schema) => (data) => {
     );
   }
 
-  return Object.keys(data).reduce((acc, key) => {
+  const reducer = (acc, key) => {
     const value = data[key];
     const transform = schema[key];
     const transformType = typeof transform;
+
     /* eslint-disable no-nested-ternary */
     const nextValue =
       transformType === 'function'
@@ -38,7 +39,21 @@ const evolve = (schema) => (data) => {
     /* eslint-enable no-nested-ternary */
 
     return isArray ? acc.concat(nextValue) : { ...acc, [key]: nextValue };
-  }, result);
+  };
+
+  const nextData = Object.keys(data).reduce(reducer, result);
+
+  if (strict) {
+    // Strict mode ensures all keys in expected schema are present
+    // in the returned payload.
+    return Object.keys(schema)
+      .filter((expectedKey) => {
+        return !Object.prototype.hasOwnProperty.call(data, expectedKey);
+      })
+      .reduce(reducer, nextData);
+  }
+
+  return nextData;
 };
 
 module.exports = evolve;

lib/next/validateMessage.js

@@ -1,15 +1,25 @@
 const isset = require('../utils/isset');
+const { coerce, coerceWeak } = require('./units/coerce');
 const { normalize } = require('./units/normalize');
 const { isValid } = require('./units/isValid');
 const { validateStatusCode } = require('./units/validateStatusCode');
 const { validateHeaders } = require('./units/validateHeaders');
 const { validateBody } = require('./units/validateBody');
 
 function validateMessage(realMessage, expectedMessage) {
-  const real = normalize(realMessage);
-  const expected = normalize(expectedMessage);
   const results = {};
 
+  // Uses strict coercion on real message.
+  // Strict coercion ensures real message has properties illegible
+  // for validation with the expected message.
+  const real = normalize(coerce(realMessage));
+
+  // Weak coercion applies transformation only to the properties
+  // present in the given message. We don't want to mutate user's assertion.
+  // However, we do want to use the same coercion logic we do
+  // for strict coercion. Thus normalization and coercion are separate.
+  const expected = normalize(coerceWeak(expectedMessage));
+
   if (real.statusCode) {
     results.statusCode = validateStatusCode(real, expected);
   }
@@ -25,6 +35,7 @@ function validateMessage(realMessage, expectedMessage) {
     results.body = validateBody(real, expected);
   }
 
+  // Indicates the validity of the real message
   results.isValid = isValid(results);
 
   return results;