Stricten test and some docs. Closes #3002 and #3410

lib/associations/mixin.js

@@ -222,7 +222,7 @@ Mixin.belongsTo = singleLinked(BelongsTo);
  *
  * Similarily, when fetching through a join table with custom attributes, these attributes will be available as an object with the name of the through model.
  * ```js
- * user.getProjects().success(function (projects) {
+ * user.getProjects().then(function (projects) {
  *   var p1 = projects[0]
  *   p1.userprojects.started // Is this project started yet?
  * })

lib/model.js

@@ -909,7 +909,8 @@ module.exports = (function() {
    *   where: ...,
    *   limit: 12,
    *   offset: 12
-   * }).success(function (result) {
+   * }).then(function (result) {
+   *   ...
    * })
    * ```
    * In the above example, `result.rows` will contain rows 13 through 24, while `result.count` will return the total number of rows that matched your query.
@@ -1148,8 +1149,8 @@ module.exports = (function() {
    * @param {Object}   options
    * @param {Object}   options.where where A hash of search attributes.
    * @param {Object}   [options.defaults] Default values to use if creating a new instance
-   * @param {Function} [options.logging=false] A function that gets executed while running the query to log the sql.
    *
+   * @see {Model#findAll} for a specification of find and options
    * @return {Promise<Instance,created>}
    */
   Model.prototype.findOrCreate = function(options) {

test/integration/model/json.test.js

@@ -19,12 +19,46 @@ describe(Support.getTestDialectTeaser('Model'), function() {
             type: DataTypes.JSONB,
             field: 'event_data',
             index: true
-          }
+          },
+          json: DataTypes.JSON
         });
 
         return this.Event.sync({force: true});
       });
 
+      if (current.dialect.supports.lock) {
+        it('findOrCreate supports transactions, json and locks', function() {
+          var self = this;
+          return current.transaction().then(function(t) {
+            return self.Event.findOrCreate({
+              where: {
+                json: { some: { input: 'Hello' } }
+              },
+              defaults: {
+                json: { some: { input: 'Hello' }, input: [1, 2, 3] },
+                data: { some: { input: 'There' }, input: [4, 5, 6] }
+              },
+              transaction: t,
+              lock: t.LOCK.UPDATE,
+              logging: function (sql) {
+                if (sql.indexOf('SELECT') !== -1 && sql.indexOf('CREATE') === -1) {
+                  expect(sql.indexOf('FOR UPDATE')).not.to.be.equal(-1);
+                }
+              }
+            }).then(function() {
+              return self.Event.count().then(function(count) {
+                expect(count).to.equal(0);
+                return t.commit().then(function() {
+                  return self.Event.count().then(function(count) {
+                    expect(count).to.equal(1);
+                  });
+                });
+              });
+            });
+          });
+        });
+      }
+
       it('should create an instance with JSONB data', function () {
         return this.Event.create({
           data: {