Nascent Political Miscreant


    1.3.0 • Public • Published
    # specify

    specify is the simplest way i could think to do node.js testing.

    It works with sync code and async code all the same.

    Please use versions ~0.6.x for node 0.6 and ~1.0.x for node 0.8 or higher.

    If you don't like reading and want to see some code you can look at nano's tests and learn there. Also read the specify source code; it's just a couple of lines of code.

    var specify = require('specify');
    specify('create_by_secret', function (assert) {
      user.create_by_secret({invitation_code: "1234321!!"}, function (err) {
        assert.equal(err.eid, "ec:api:user:create_by_secret:wrong_code");
        assert.equal(err.status_code, 400);

    The assert calls are callback functions that wrap the assert module. specify figures out how many callbacks you are calling by static-analysis. To put it simply, it counts the number of times you wrote assert. When that number of assertions is met, or when a timeout occurs, that test is complete and we can execute the next one.

    Static analysis does not work for a for loop and some other flow control constructs. In that case you can use assert.expect(nr) to tell specify how many assertions to expect:

    specify('more_assertions_than_asserts', function(assert) {
      for(var i in [1,2,3,4,5]) {

    specify runs tests one by one, not in parallel. If you set assert.expect higher than the number of assert function calls the execution will stop, and your current test will never finish. You can circumvent this by setting a timeout:

    specify('foo', 50, function (assert) {
      call_to_db_that_takes_a_long_time(function (data) {
        assert.equal(data, 'foo');

    Because tests are serialized, specify can catch uncaught exceptions and continue to run. You will get a report about the error that was thrown somewhere in your stack. This is analogous to the functionality the community refers to as domains.

    specify is standalone; you don't need any special binaries to run it.

    If you think all these specify functions make your code look bloated, you can also run a single function:

    var specify = require('specify')
      , request = require('request')

      function (assert) {
        var get = { uri: "", json: true }
          , del = { uri: "", method: "DELETE"
                  , json : true }
          , app_name
        request(get, function (err, _, body) {
          assert.ok(body.total_rows >= 1);
          assert.ok(body.rows.length >= 1);
          app_name = body.rows[0].value.app_name;
          del.uri += "/" + app_name;
          request(del, function (err, resp, body) {
            assert.equal(resp.statusCode, 200);
            assert.equal(, app_name);
    # installation ## node.js
    1. install npm
    2. npm install specify
    3. var specify = require('specify');
    # filtering

    In specify you specify which tests you want to run:

    var specify = require('specify')
      , filters = process.argv.slice(2)
    specify('foo', function (assert) {
      assert.equal('foo', 'foo');
    specify('bar', function (assert) {
      assert.equal('bar', 'baz', 'bar failed');
    specify('baz', function (assert) {
      assert.equal('baz', 'baz');
    # reporters

    If you feel like the output sent to stdout is ugly, you can write your own reporter and send in a pull request.

    Now use it:

    specify('specify#ask_for_a_specific_reporter', function(assert) {
      setTimeout(function (){

    You can also do this with a function if you like:

    specify('specify#custom_reporter_from_function', function(assert) {
      specify.reporter(function (name, report, errors) {
      setTimeout(function () {
        assert.ok(false, 'i see dead people');
    # samples

    Samples are available in the /test folder.

    # contribute

    Everyone is welcome to contribute. Patches, bug-fixes, reporters, new features.

    1. Create an issue so the community can comment on your idea
    2. Fork specify
    3. Create a new branch git checkout -b feature_name
    4. Create tests for the changes you made
    5. Make sure you pass both existing and newly inserted tests
    6. Commit your changes
    7. Push to your branch git push origin feature_name
    8. Create a pull request
    # meta

    (oO)--',- in caos

    # license

    Copyright 2012 nuno job <> (oO)--',--

    Licensed under the apache license, version 2.0 (the "license"); You may not use this file except in compliance with the license. You may obtain a copy of the license at

    Unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.


    npm i specify

    DownloadsWeekly Downloads






    Last publish


    • dscape