docs(Model): Fix Model.validate() documentation (#7774)

docs/upgrade-to-v4.md

@@ -85,6 +85,7 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
 
 
 - `DATEONLY` now returns string in `YYYY-MM-DD` format rather than `Date` type
 - `DATEONLY` now returns string in `YYYY-MM-DD` format rather than `Date` type
 - `Model.validate` instance method now runs validation hooks by default. Previously you needed to pass `{ hooks: true }`. You can override this behavior by passing `{ hooks: false }`
 - `Model.validate` instance method now runs validation hooks by default. Previously you needed to pass `{ hooks: true }`. You can override this behavior by passing `{ hooks: false }`
+- The resulting promise from the `Model.validate` instance method will be rejected when validation fails. It will fulfill when validation succeeds.
 - Raw options for where, order and group like `where: { $raw: '..', order: [{ raw: '..' }], group: [{ raw: '..' }] }` have been removed to prevent SQL injection attacks.
 - Raw options for where, order and group like `where: { $raw: '..', order: [{ raw: '..' }], group: [{ raw: '..' }] }` have been removed to prevent SQL injection attacks.
 
 
 ### New features
 ### New features

lib/model.js

@@ -3722,14 +3722,14 @@ class Model {
   /**
   /**
   * Validate the attributes of this instance according to validation rules set in the model definition.
   * Validate the attributes of this instance according to validation rules set in the model definition.
   *
   *
-  * Emits null if and only if validation successful; otherwise an Error instance containing { field name : [error msgs] } entries.
+  * The promise fulfills if and only if validation successful; otherwise it rejects an Error instance containing { field name : [error msgs] } entries.
   *
   *
   * @param {Object} [options] Options that are passed to the validator
   * @param {Object} [options] Options that are passed to the validator
   * @param {Array} [options.skip] An array of strings. All properties that are in this array will not be validated
   * @param {Array} [options.skip] An array of strings. All properties that are in this array will not be validated
   * @param {Array} [options.fields] An array of strings. Only the properties that are in this array will be validated
   * @param {Array} [options.fields] An array of strings. Only the properties that are in this array will be validated
   * @param {Boolean} [options.hooks=true] Run before and after validate hooks
   * @param {Boolean} [options.hooks=true] Run before and after validate hooks
   *
   *
-  * @return {Promise<undefined|Errors.ValidationError>}
+  * @return {Promise<undefined>}
   */
   */
   validate(options) {
   validate(options) {
     return new InstanceValidator(this, options).validate();
     return new InstanceValidator(this, options).validate();

test/unit/instance-validator.test.js

@@ -10,7 +10,18 @@ const SequelizeValidationError = require('../../lib/errors').ValidationError;
 
 
 describe(Support.getTestDialectTeaser('InstanceValidator'), () => {
 describe(Support.getTestDialectTeaser('InstanceValidator'), () => {
   beforeEach(() => {
   beforeEach(() => {
-    this.User = Support.sequelize.define('user');
+    this.User = Support.sequelize.define('user', {
+      fails: {
+        type: Support.Sequelize.BOOLEAN,
+        validate: {
+          isNotTrue(value) {
+            if (value) {
+              throw Error('Manual model validation failure');
+            }
+          }
+        }
+      }
+    });
   });
   });
 
 
   it('configures itself to run hooks by default', () => {
   it('configures itself to run hooks by default', () => {
@@ -40,6 +51,20 @@ describe(Support.getTestDialectTeaser('InstanceValidator'), () => {
       expect(_validate).to.have.been.calledOnce;
       expect(_validate).to.have.been.calledOnce;
       expect(_validateAndRunHooks).to.not.have.been.called;
       expect(_validateAndRunHooks).to.not.have.been.called;
     });
     });
+
+    it('fulfills when validation is successful', () => {
+      const instanceValidator = new InstanceValidator(this.User.build());
+      const result = instanceValidator.validate();
+
+      return expect(result).to.be.fulfilled;
+    });
+
+    it('rejects with a validation error when validation fails', () => {
+      const instanceValidator = new InstanceValidator(this.User.build({ fails: true }));
+      const result = instanceValidator.validate();
+
+      return expect(result).to.be.rejectedWith(SequelizeValidationError);
+    });
   });
   });
 
 
   describe('_validateAndRunHooks', () => {
   describe('_validateAndRunHooks', () => {