RFC: syntax sugar for mocha tests calling multiple async functions

rfc.js

// Original code
it('does something complex', function(done) {
  async.waterfall(
    [
      function setupSchema(cb) {
        db.setupSchema(/*...*/, cb);
      },
      function createTestUser(cb) {
        db.createUser({ name: 'a user name' }, cb);
      }
      function act(data, cb) {
        this.data = data;
        db.users.edit(this.data.UserId, { name: 'new name' }, cb);
      },
      function assert(cb) {
        db.users.findById(this.data.userId, function(user) {
          expect(user.name).to.equal('new name');
          cb();
        }
      }
    ],
    done);
});

// Proposed API:
it('does something complex', [
  function setupSchema(cb) {
    db.setupSchema(/*...*/, cb);
  },
  function createTestUser(cb) {
    db.createUser({ name: 'a user name' }, cb);
  }
  function act(data, cb) {
    this.data = data;
    db.users.edit(this.data.UserId, { name: 'new name' }, cb);
  },
  function fetchNewData(cb) {
    db.users.findById(this.data.userId, cb);
  },
  function assert(user, cb) {
    expect(user.name).to.equal('new name');
    cb();
  }
]);

Thank you all for valuable comments. Because the main reason behind the high number of waterfall steps is the code for building models (as Ryan pointed out), I decided to simplify that piece.

This is my current code:

it('sends notification to the correct device', function(done) {
  var context = {};
  async.waterfall([
    function arrange(cb) {
      context.pushManager = new PushManager();
      var builder = new TestDataBuilder();
      builder
        .def('application', Application, {
          pushSettings: { stub: { } }
        })
        .def('anotherDevice', Device, {
          appId: builder.ref('application.id'),
          deviceType: 'another-device-type'
        })
        .def('device', Device, {
          appId: builder.ref('application.id'),
          deviceType: mockery.deviceType
        })
        .def('notification', Notification)
        .buildToContext(context, cb);
    },

    function act(cb) {
      context.pushManager.pushNotificationByRegistrationId(
        context.device.id,
        context.notification,
        cb
      );
    },

    function assert(cb) {
      expect(mockery.firstPushNotificationArgs())
        .to.deep.equal([context.notification, context.device.deviceToken]);
      cb();
    }
  ], done);
});

How do you like that?

I'll leave the implementation in loopback-push-notification for now, later we can move it to a standalone module and write a blogpost on usage.

I have to agree that I'm on the "less magic" side, as @bajtos should know from my response to his email thread. That said, if you want to go down the "waterfall, building data as you go" model, let me shamelessly plug Stepdown: https://github.com/schoonology/stepdown . That's exactly what it does.