将“done”函数传递给Karma的服务器时为什么会出现gulp错误？

Question

Just writing a (so far) very simple gulpfile and I am perplexed by an error I have come across.

When the tests fail with this task, gulp exits gracefully

gulp.task('test', done => {
    new KarmaServer({
        configFile: __dirname + '/karma.conf.js',
        singleRun: true
    }, () => done()).start();
});

...produces:

Chrome 50.0.2661 (Mac OS X 10.11.3): Executed 11 of 11 (3 FAILED) (0.053 secs / 0.023 secs)
[17:38:02] Finished 'test' after 2.43 s

But when you slim it down to just pass done into Karma, it fails rather ungracefully

gulp.task('test', done => {
    new KarmaServer({
        configFile: __dirname + '/karma.conf.js',
        singleRun: true
    }, done).start();
});

...produces:

Chrome 50.0.2661 (Mac OS X 10.11.3): Executed 11 of 11 (3 FAILED) (0.066 secs / 0.042 secs)
[17:36:39] 'test' errored after 2.45 s
[17:36:39] Error: 1
    at formatError (/usr/local/lib/node_modules/gulp/bin/gulp.js:169:10)
    at Gulp.<anonymous> (/usr/local/lib/node_modules/gulp/bin/gulp.js:195:15)
    at emitOne (events.js:77:13)
    at Gulp.emit (events.js:169:7)
    at Gulp.Orchestrator._emitTaskDone (/Users/markstickley/workspace/timewarp/node_modules/gulp/node_modules/orchestrator/index.js:264:8)
    at /Users/markstickley/workspace/timewarp/node_modules/gulp/node_modules/orchestrator/index.js:275:23
    at finish (/Users/markstickley/workspace/timewarp/node_modules/gulp/node_modules/orchestrator/lib/runTask.js:21:8)
    at cb (/Users/markstickley/workspace/timewarp/node_modules/gulp/node_modules/orchestrator/lib/runTask.js:29:3)
    at removeAllListeners (/Users/markstickley/workspace/timewarp/node_modules/karma/lib/server.js:336:7)
    at Server.<anonymous> (/Users/markstickley/workspace/timewarp/node_modules/karma/lib/server.js:347:9)
    at Server.g (events.js:260:16)
    at emitNone (events.js:72:20)
    at Server.emit (events.js:166:7)
    at emitCloseNT (net.js:1518:8)
    at doNTCallback1 (node.js:418:9)
    at process._tickCallback (node.js:340:17)

Can anyone explain why this happens, given that done is a function and all the wrapped version of done does is call done ?

Answer 1

Further research has revealed that Karma resolves the callback passed to it with an exit code ( https://karma-runner.github.io/0.13/dev/public-api.html ):

var Server = require('karma').Server
var server = new Server({port: 9876}, function(exitCode) {
  console.log('Karma has exited with ' + exitCode)
  process.exit(exitCode)
})

And that gulp will quit the run if done is passed any argument other than null or undefined ( https://github.com/gulpjs/gulp/blob/master/docs/API.md#gulptaskname--deps-fn ):

gulp.task('one', function(cb) {
    // do stuff -- async or otherwise
    cb(err); // if err is not null and not undefined, the run will stop, and note that it failed
});

So Karma's exit code is causing gulp to exit prematurely when done is passed directly to Karma as a callback. Wrapping it in a function means that done is still called but without any arguments -- causing normal completion.

Answer 2

Mark,

A couple of things.

I had exactly the same issue understanding what gulp was doing with the callback and how it all worked. First and foremost we must understand that gulp allows you to have two syntaxes. One where you return from the task function and gulp can get on with its subsequent tasks, and the other where you must provide a callback for the same purpose. These are equivalent:

gulp.task('Returns', function(){
    return gulp.src(...).pipe(...)
})

gulp.task('Returns', function(done){
    gulp.src(...).pipe(...)
})

On the other hand javascript being the powerful language that it is allows us to write some horrific and terror inducing code. For that reason I like to break things down a little.

Translating the first function into human readable code:

Step 1

function get_karma_server(){
    return new KarmaServer({
        configFile: __dirname + '/karma.conf.js',
        singleRun: true
    }
}

gulp.task('test', done => {
    get_karma_server }, () => done()).start();
});

done is defined as the content of whatever is inside { } curly braces. Comma . But a gulp task requires a function to execute. Ok, the function to execute is the execution of get_karma_server which returns the instance of the server and .start()

If that doesn't make you vomit I don't know what does.

This is why it doesn't work

If you don't execute the function then you don't have an instance of the server ,which means that start is not a function of undefined which means that gulp doesn't get its callback. Hence all the callback related errors.

Step 2

function get_karma_server(){
    return new KarmaServer({
        configFile: __dirname + '/karma.conf.js',
        singleRun: true
    }
}

gulp.task('test', function(done){
    get_karma_server().start();
});

Still equivalent, but now it makes a little more sense. done is still the callback to gulp.

Step 3

function get_karma_server(){
    return new KarmaServer({
        configFile: __dirname + '/karma.conf.js',
        singleRun: true
    }
}

gulp.task('test', function(){
    return get_karma_server().start();
});

The same function but this time we just return instead of providing a callback if you are not using it.

Suggestion

gulp.task('test', function(the_gulp_callback_aka_done){

    // Initialize and get the instance of the server
    var karma = require('karma').Server;

    // setup your configuration. This could live somewhere else
    var config = {
        configFile: __dirname + '/karma.conf.js',
        singleRun: true
    };

    // the karma callback
    function karma_Callback(){
        // Do something here after karma is done running your tests
    }

    karma.start(config, karma_Callback);
});

Be verbose. It is not any slower at run-time and it is a heck of a lot faster to understand.

-------------- Edit --------------

@Mark, my apologizes. I understood the question but did not convey the message. It is not a matter of ES5 vs ES6.

The parenthesis () syntax is used for execution, right?. You can execute something that is not a function but javascript will try to execute it nonetheless giving errors and what not.

In this case you could just provide karma with a function by name, say x, then karma will take x and call () on it by means of x(). Right? This is because it is expecting x to be a function to call after it is done processing your tests. Hence the call-back.

Now, within x javascript will execute everything just like a regular function but then it runs into this done thing and it does not know what to do with it because x itself does not take a call back.

In code:

function x(){
    // get things done here
}

function x(callback_for_x){
    // get things done here

    // ok, I'm done. call the callback_for_x
    callback_for_x();
}

Using done within this version of x:

function x(){
    // get things done here
    // and...
    done; // Get ready for some errors
}

Using done here will work just fine.

function x(callback_for_x){
    // get things done here

    // ok, I'm done. call the callback_for_x
    callback_for_x();
}

However, we have the first version of x as a callback to karma, which means that we must manually call done:

function x(){
    // get things done here
    // and...
    done(); // Now gulp can continue because it's callback was called.
}

I hope that made more sense. I hate it when I'm incoherent and this post has gone longer than it was supposed to.