simple, flexible, fun

Mocha是一个功能丰富的JavaScript测试框架,可在Node.js和浏览器中运行,从而使异步测试变得简单有趣 . Mocha测试按顺序运行,从而可以灵活,准确地报告,同时将未捕获的异常映射到正确的测试用例. 托管在GitHub上 .

Backers

发现摩卡咖啡有帮助? 成为支持者并通过每月捐款来支持Mocha.

Sponsors

在工作中使用摩卡咖啡? 询问您的经理或营销团队是否会帮助支持我们的项目. 您公司的徽标也将显示在npmjs.com和我们的GitHub存储库上 .

Features

Table of Contents

Installation

全局安装npm

$ npm install --global mocha

或作为项目的开发依赖项:

$ npm install --save-dev mocha

从v7.0.0开始,Mocha需要Node.js v8.0.0或更高版本.

Getting Started

$ npm install mocha
$ mkdir test
$ $EDITOR test/test.js # or open with your favorite editor

在您的编辑器中:

var assert = require('assert');
describe('Array', function() {
  describe('#indexOf()', function() {
    it('should return -1 when the value is not present', function() {
      assert.equal([1, 2, 3].indexOf(4), -1);
    });
  });
});

回到终端:

$ ./node_modules/mocha/bin/mocha

  Array
    #indexOf()
      ✓ should return -1 when the value is not present


  1 passing (9ms)

在package.json中设置测试脚本:

"scripts": {
  "test": "mocha"
}

然后使用以下命令运行测试:

$ npm test

Run Cycle Overview

关于执行Mocha组件顺序的简要概述. 值得注意的是,所有的钩子, describeit的回调在它们被定义的顺序运行(即在文件中找到).

run 'mocha spec.js'
|
spawn child process
|
|--------------> inside child process
  process and apply options
  |
  run spec file/s
  |
  |--------------> per spec file
    suite callbacks (e.g., 'describe')
    |
    'before' root-level pre-hook
    |
    'before' pre-hook
    |
    |--------------> per test
      'beforeEach' root-level pre-hook
      |
      'beforeEach' pre-hook
      |
      test callbacks (e.g., 'it')
      |
      'afterEach' post-hook
      |
      'afterEach' root-level post-hook
    |<-------------- per test end
    |
    'after' post-hook
    |
    'after' root-level post-hooks
  |<-------------- per spec file end
|<-------------- inside child process end

Detects Multiple Calls to done()

如果使用基于回调的异步测试,则如果多次调用done() ,则Mocha将引发错误. 这对于捕获意外的双回调很方便.

it('double done', function(done) {
  // Calling `done()` twice is an error
  setImmediate(done);
  setImmediate(done);
});

运行上面的测试将给您以下错误消息:

$ ./node_modules/.bin/mocha mocha.test.js


  ✓ double done
  1) double done

  1 passing (6ms)
  1 failing

  1) double done:
     Error: done() called multiple times
      at Object.<anonymous> (mocha.test.js:1:63)
      at require (internal/module.js:11:18)
      at Array.forEach (<anonymous>)
      at startup (bootstrap_node.js:187:16)
      at bootstrap_node.js:608:3

Assertions

Mocha允许您使用所需的任何断言库. 在上面的示例中,我们使用Node.js的内置assert模块-但是通常,如果抛出Error ,它将起作用! 这意味着您可以使用以下库:

Asynchronous Code

使用Mocha测试异步代码再简单不过了! 测试完成后,只需调用回调即可. 通过向it()添加回调(通常命名为done ),Mocha将知道它应该等待调用此函数来完成测试. 该回调既接受Error实例(或其子类), 接受伪造的值. 其他所有内容均无效,并引发错误(通常会导致测试失败).

describe('User', function() {
  describe('#save()', function() {
    it('should save without error', function(done) {
      var user = new User('Luna');
      user.save(function(err) {
        if (err) done(err);
        else done();
      });
    });
  });
});

或者,直接使用done()回调(它将处理错误参数,如果存在):

describe('User', function() {
  describe('#save()', function() {
    it('should save without error', function(done) {
      var user = new User('Luna');
      user.save(done);
    });
  });
});

Working with Promises

或者,您可以返回Promise ,而不是使用done()回调. 如果您正在测试的API返回承诺而不是采用回调,则此方法很有用:

beforeEach(function() {
  return db.clear().then(function() {
    return db.save([tobi, loki, jane]);
  });
});

describe('#find()', function() {
  it('respond with matching records', function() {
    return db.find({type: 'User'}).should.eventually.have.length(3);
  });
});

后一个示例将Chai用作对流利的诺言断言的承诺.

在Mocha v3.0.0和更高版本中,返回Promise 调用done()将导致异常,因为通常这是一个错误:

const assert = require('assert');

// antipattern
it('should complete this test', function(done) {
  return new Promise(function(resolve) {
    assert.ok(true);
    resolve();
  }).then(done);
});

上面的测试将失败,并显示Error: Resolution method is overspecified. Specify a callback *or* return a Promise; not both. Error: Resolution method is overspecified. Specify a callback *or* return a Promise; not both. . 在v3.0.0之前的版本中,对done()的调用实际上被忽略.

Using async / await

如果您的JS环境支持async / await ,那么您还可以编写如下异步测试:

beforeEach(async function() {
  await db.clear();
  await db.save([tobi, loki, jane]);
});

describe('#find()', function() {
  it('responds with matching records', async function() {
    const users = await db.find({type: 'User'});
    users.should.have.length(3);
  });
});

Synchronous Code

测试同步代码时,省略回调,Mocha将自动继续进行下一个测试.

describe('Array', function() {
  describe('#indexOf()', function() {
    it('should return -1 when the value is not present', function() {
      [1, 2, 3].indexOf(5).should.equal(-1);
      [1, 2, 3].indexOf(0).should.equal(-1);
    });
  });
});

Arrow Functions

不建议将箭头函数 (也称为" lambdas")传递给Mocha. Lambda以词法绑定this ,并且无法访问Mocha上下文. 例如,以下代码将失败:

describe('my suite', () => {
  it('my test', () => {
    // should set the timeout of this test to 1000 ms; instead will fail
    this.timeout(1000);
    assert.ok(true);
  });
});

如果您不需要使用 Mocha的上下文,则lambdas应该起作用. 但是,如果最终需要,结果将难以重构.

Hooks

通过其默认的" BDD"样式接口,Mocha提供了钩子before()after()beforeEach()afterEach() . 这些应用于设置前提条件并在测试后清除.

describe('hooks', function() {
  before(function() {
    // runs before all tests in this block
  });

  after(function() {
    // runs after all tests in this block
  });

  beforeEach(function() {
    // runs before each test in this block
  });

  afterEach(function() {
    // runs after each test in this block
  });

  // test cases
});

测试可以出现在钩子之前,之后或之间. 挂钩将按照定义的顺序运行; 所有before()挂钩都运行一次,然后再运行任何beforeEach()挂钩,测试,任何afterEach()挂钩,最后是after()挂钩(一次).

Describing Hooks

任何挂钩都可以通过可选的描述来调用,从而更容易在测试中查明错误. 如果为挂钩提供了命名函数,则在未提供描述的情况下将使用该名称.

beforeEach(function() {
  // beforeEach hook
});

beforeEach(function namedFun() {
  // beforeEach:namedFun
});

beforeEach('some description', function() {
  // beforeEach:some description
});

Asynchronous Hooks

所有钩子( before()after()beforeEach()afterEach() )也可以同步或异步,其行为与常规测试用例非常相似. 例如,您可能希望在每次测试之前用虚拟内容填充数据库:

describe('Connection', function() {
  var db = new Connection(),
    tobi = new User('tobi'),
    loki = new User('loki'),
    jane = new User('jane');

  beforeEach(function(done) {
    db.clear(function(err) {
      if (err) return done(err);
      db.save([tobi, loki, jane], done);
    });
  });

  describe('#find()', function() {
    it('respond with matching records', function(done) {
      db.find({type: 'User'}, function(err, res) {
        if (err) return done(err);
        res.should.have.length(3);
        done();
      });
    });
  });
});

Root-Level Hooks

您也可以选择任何文件并添加"根"级挂钩. 例如,在所有describe()块之外添加beforeEach() . 这将导致对beforeEach()的回调在任何测试用例之前运行,无论它位于哪个文件中(这是因为Mocha具有隐式 describe()块,称为"根套件").

beforeEach(function() {
  console.log('before every test in every file');
});

Delayed Root Suite

如果需要在运行任何套件之前执行异步操作,则可以延迟根套件. 使用--delay标志运行mocha . 这会将特殊的回调函数run()附加到全局上下文:

setTimeout(function() {
  // do some setup

  describe('my suite', function() {
    // ...
  });

  run();
}, 5000);

Pending Tests

"待定"-就像"最终应该写这些测试用例的人"中一样-测试用例就是那些没有回调的用例:

describe('Array', function() {
  describe('#indexOf()', function() {
    // pending test below
    it('should return -1 when the value is not present');
  });
});

待定测试将包括在测试结果中,并标记为待定. 暂挂测试不视为失败测试.

Exclusive Tests

排他性功能允许您通过将.only()附加到函数中来运行指定的套件或测试用例. 这是仅执行特定套件的示例:

describe('Array', function() {
  describe.only('#indexOf()', function() {
    // ...
  });
});

注意 :所有嵌套套件仍将执行.

这是执行单个测试用例的示例:

describe('Array', function() {
  describe('#indexOf()', function() {
    it.only('should return -1 unless present', function() {
      // ...
    });

    it('should return the index when present', function() {
      // ...
    });
  });
});

在v3.0.0之前, .only()使用字符串匹配来确定要执行的测试; 这已不再是这种情况. 在v3.0.0或更高版本中, .only()可以多次使用以定义要运行的测试的子集:

describe('Array', function() {
  describe('#indexOf()', function() {
    it.only('should return -1 unless present', function() {
      // this test will be run
    });

    it.only('should return the index when present', function() {
      // this test will also be run
    });

    it('should return -1 if called with a non-Array context', function() {
      // this test will not be run
    });
  });
});

您还可以选择多个套件:

describe('Array', function() {
  describe.only('#indexOf()', function() {
    it('should return -1 unless present', function() {
      // this test will be run
    });

    it('should return the index when present', function() {
      // this test will also be run
    });
  });

  describe.only('#concat()', function() {
    it('should return a new Array', function() {
      // this test will also be run
    });
  });

  describe('#slice()', function() {
    it('should return a new Array', function() {
      // this test will not be run
    });
  });
});

But 测试将优先:

describe('Array', function() {
  describe.only('#indexOf()', function() {
    it.only('should return -1 unless present', function() {
      // this test will be run
    });

    it('should return the index when present', function() {
      // this test will not be run
    });
  });
});

注意 :挂钩(如果存在)仍将执行.

注意不要将.only()用法提交给版本控制,除非您真的是这样! 为此,可以在持续集成测试命令中(或在git precommit挂钩中)使用--forbid-only选项运行mocha.

Inclusive Tests

此功能与.only()相反. 通过附加.skip() ,您可以告诉Mocha简单地忽略测试用例. 跳过的所有内容都将标记为未决 ,并以此报告. 这是跳过单个测试的示例:

describe('Array', function() {
  describe('#indexOf()', function() {
    it.skip('should return -1 unless present', function() {
      // this test will not be run
    });

    it('should return the index when present', function() {
      // this test will be run
    });
  });
});

您还可以将.skip()放在整个套件上. 这等效于将.skip()附加到套件中的所有测试上. 套件中的挂钩也被跳过.

describe('Array', function() {
  describe.skip('#indexOf()', function() {
    it('should return -1 unless present', function() {
      // this test will not be run
    });
  });
});

注意 :跳过套件中位于钩子或测试之外的代码仍将执行,因为mocha仍将调用套件功能来建立套件结构以进行可视化.

最佳实践 :使用.skip()而不是注释掉测试.

您也可以使用this.skip() 在运行时跳过. 如果测试需要无法事先检测到的环境或配置,则可以使用运行时跳过. 例如:

it('should only test in the correct environment', function() {
  if (/* check test environment */) {
    // make assertions
  } else {
    this.skip();
  }
});

以上测试将报告为未决 . 同样重要的是要注意,调用this.skip()将有效地中止测试.

最佳实践 :为避免混淆,请在调用this.skip()之后不要在测试或钩子中执行更多指令.

将上面的测试与以下代码进行对比:

it('should only test in the correct environment', function() {
  if (/* check test environment */) {
    // make assertions
  } else {
    // do nothing
  }
});

由于此测试不执行任何操作 ,因此将报告为通过 .

最佳实践: Don't do nothing! A test should make an assertion or use this.skip().

要以这种方式跳过多个测试,请在" before all"挂钩中使用this.skip()

before(function() {
  if (/* check test environment */) {
    // setup code
  } else {
    this.skip();
  }
});

这将跳过所有itbeforeEach/afterEach ,并describe套件describe块. 除非在与包含this.skip()的钩子相同的级别上定义钩子,否则将跳过before/after钩子.

describe('outer', function() {
  before(function() {
    this.skip();
  });

  after(function() {
    // will be executed
  });

  describe('inner', function() {
    before(function() {
      // will be skipped
    });

    after(function() {
      // will be skipped
    });
  });
});

在v7.0.0中更新. 不允许在"毕竟"挂钩中跳过测试,这将引发异常. 使用return语句或其他方式中止挂钩执行.

在Mocha v3.0.0之前,异步测试和挂钩不支持this.skip() .

Retry Tests

您可以选择最多重试失败的测试几次. 此功能旨在处理无法轻松模拟/存根资源的端到端测试(功能测试/ Selenium ...). 不建议将此功能用于单元测试 .

此功能会在beforeEach/afterEach挂钩before/after重新运行,但不会before/after挂钩上重新运行.

注意 :以下示例是使用Selenium Webdriver( 覆盖 Promise链的全局Mocha钩子 )编写的.

describe('retries', function() {
  // Retry all tests in this suite up to 4 times
  this.retries(4);

  beforeEach(function() {
    browser.get('http://www.yahoo.com');
  });

  it('should succeed on the 3rd try', function() {
    // Specify this test to only retry up to 2 times
    this.retries(2);
    expect($('.foo').isDisplayed()).to.eventually.be.true;
  });
});

Dynamically Generating Tests

鉴于Mocha使用Function.prototype.call和函数表达式来定义套件和测试用例,可以轻松地动态生成测试. 不需要特殊的语法-普通的JavaScript可用于实现类似于"参数化"测试的功能,您可能已经在其他框架中看到了这种功能.

请看以下示例:

var assert = require('chai').assert;

function add() {
  return Array.prototype.slice.call(arguments).reduce(function(prev, curr) {
    return prev + curr;
  }, 0);
}

describe('add()', function() {
  var tests = [
    {args: [1, 2], expected: 3},
    {args: [1, 2, 3], expected: 6},
    {args: [1, 2, 3, 4], expected: 10}
  ];

  tests.forEach(function(test) {
    it('correctly adds ' + test.args.length + ' args', function() {
      var res = add.apply(null, test.args);
      assert.equal(res, test.expected);
    });
  });
});

上面的代码将产生具有三个规格的套件:

$ mocha

  add()
    ✓ correctly adds 2 args
    ✓ correctly adds 3 args
    ✓ correctly adds 4 args

Test duration

许多报告程序将显示测试持续时间和标志测试,这些测试速度很慢(默认值:75ms),如此处的" spec"报告程序所示:

test duration

测试持续时间分为三个级别(如下图所示):

  1. 快速:运行在"慢速"阈值一半以内的测试将以绿色显示持续时间(如果有的话).
  2. 正常:运行超过阈值一半(但仍在阈值范围内)的测试将以黄色显示持续时间.
  3. 慢:超过阈值的测试将以红色显示持续时间.

test duration range

要调整" slow",可以使用slow()方法:

describe('something slow', function() {
  this.slow(300000); // five minutes

  it('should take long enough for me to go make a sandwich', function() {
    // ...
  });
});

Timeouts

Suite-level

套件级别的超时可以应用于整个测试"套件",也可以通过this.timeout(0)禁用. 这将被所有不覆盖该值的嵌套套件和测试用例继承.

describe('a suite of tests', function() {
  this.timeout(500);

  it('should take less than 500ms', function(done) {
    setTimeout(done, 300);
  });

  it('should take less than 500ms as well', function(done) {
    setTimeout(done, 250);
  });
});

Test-level

也可以应用特定于测试的超时,或者使用this.timeout(0)一起禁用超时:

it('should take less than 500ms', function(done) {
  this.timeout(500);
  setTimeout(done, 300);
});

Hook-level

挂钩级超时也可能适用:

describe('a suite of tests', function() {
  beforeEach(function(done) {
    this.timeout(3000); // A very long environment setup.
    setTimeout(done, 2500);
  });
});

同样,使用this.timeout(0)禁用挂钩的超时.

在v3.0.0或更高版本中,传递给this.timeout()的参数大于最大延迟值将导致超时被禁用.

Diffs

Mocha支持从断言库中抛出的任何AssertionErrorerr.expectederr.actual属性. Mocha将尝试显示期望与断言实际所见之间的差异. 这是"字符串"差异的示例:

string diffs

Command-Line Usage


mocha [spec..]

Run tests with Mocha

Commands
  mocha inspect [spec..]  Run tests with Mocha                         [default]
  mocha init <path>       create a client-side Mocha setup at <path>

Rules & Behavior
  --allow-uncaught           Allow uncaught errors to propagate        [boolean]
  --async-only, -A           Require all tests to use a callback (async) or
                             return a Promise                          [boolean]
  --bail, -b                 Abort ("bail") after first test failure   [boolean]
  --check-leaks              Check for global variable leaks           [boolean]
  --delay                    Delay initial execution of root suite     [boolean]
  --exit                     Force Mocha to quit after tests complete  [boolean]
  --forbid-only              Fail if exclusive test(s) encountered     [boolean]
  --forbid-pending           Fail if pending test(s) encountered       [boolean]
  --global, --globals        List of allowed global variables            [array]
  --retries                  Retry failed tests this many times         [number]
  --slow, -s                 Specify "slow" test threshold (in milliseconds)
                                                          [string] [default: 75]
  --timeout, -t, --timeouts  Specify test timeout threshold (in milliseconds)
                                                        [string] [default: 2000]
  --ui, -u                   Specify user interface    [string] [default: "bdd"]

Reporting & Output
  --color, -c, --colors                     Force-enable color output  [boolean]
  --diff                                    Show diff on failure
                                                       [boolean] [default: true]
  --full-trace                              Display full stack traces  [boolean]
  --growl, -G                               Enable Growl notifications [boolean]
  --inline-diffs                            Display actual/expected differences
                                            inline within each string  [boolean]
  --reporter, -R                            Specify reporter to use
                                                      [string] [default: "spec"]
  --reporter-option, --reporter-options,    Reporter-specific options
  -O                                        (<k=v,[k1=v1,..]>)           [array]

Configuration
  --config   Path to config file           [string] [default: (nearest rc file)]
  --opts     Path to `mocha.opts` (DEPRECATED)
                                         [string] [default: "./test/mocha.opts"]
  --package  Path to package.json for config                            [string]

File Handling
  --extension          File extension(s) to load           [array] [default: js]
  --file               Specify file(s) to be loaded prior to root suite
                       execution                       [array] [default: (none)]
  --ignore, --exclude  Ignore file(s) or glob pattern(s)
                                                       [array] [default: (none)]
  --recursive          Look for tests in subdirectories                [boolean]
  --require, -r        Require module                  [array] [default: (none)]
  --sort, -S           Sort test files                                 [boolean]
  --watch, -w          Watch files in the current working directory for changes
                                                                       [boolean]
  --watch-files        List of paths or globs to watch                   [array]
  --watch-ignore       List of paths or globs to exclude from watching
                                      [array] [default: ["node_modules",".git"]]

Test Filters
  --fgrep, -f   Only run tests containing this string                   [string]
  --grep, -g    Only run tests matching this string or regexp           [string]
  --invert, -i  Inverts --grep and --fgrep matches                     [boolean]

Positional Arguments
  spec  One or more files, directories, or globs to test
                                                     [array] [default: ["test"]]

Other Options
  --help, -h         Show usage information & exit                     [boolean]
  --version, -V      Show version number & exit                        [boolean]
  --list-interfaces  List built-in user interfaces & exit              [boolean]
  --list-reporters   List built-in reporters & exit                    [boolean]

Mocha Resources
    Chat: https://gitter.im/mochajs/mocha
  GitHub: https://github.com/mochajs/mocha.git
    Docs: https://mochajs.org/

--allow-uncaught

默认情况下,Mocha将尝试捕获运行测试引发的未捕获异常并将其报告为测试失败. 使用--allow-uncaught禁用此行为,并允许传播未捕获的异常. 通常会导致进程崩溃.

在调试特别难以跟踪的异常时,此标志很有用.

--async-only, -A

强制执行一个必须以"异步"样式编写测试的规则,这意味着每个测试都提供done回调或返回Promise . 不符合要求的测试将被标记为失败.

--bail, -b

使Mocha在遇到第一个测试失败后停止运行测试. 执行相应的"每个之后"和"所有"钩子以进行潜在的清理.

--bail does not imply --exit.

--check-leaks

使用此选项可使Mocha检查运行测试时泄漏的全局变量. 通过--global选项指定可接受的全局变量(例如: --check-leaks --global jQuery --global MyLib ).

--compilers

--compilers在v6.0.0中已删除. 请参阅进一步的解释和解决方法 .

--exit

在v4.0.0中更新.

TL; DR:如果在升级到Mocha v4.0.0或更高版本后测试挂起,请使用--exit快速(尽管不一定推荐)修复程序.

默认版本v4.0.0 之前 ,Mocha将在完成所有测试后强制退出自己的进程. 这种行为会带来一系列潜在的问题. 它表示测试(或固定装置,线束,被测代码等)无法正确清理后的状态. 最终,"脏"测试可能(但并非总是)导致假阳性假阴性结果.

如果服务器仍在侦听端口或套接字仍在打开,等等,"挂起"通常会表现出来.它也可能像是setInterval()失控,甚至是从未实现的错误Promise .

v4.0.0(及更高版本)中的默认行为--no-exit ,以前是--exit .

解决问题的最简单方法是将--exit传递给Mocha进程.可以是费时调试-因为这是哪里的问题并不总是显而易见的-但建议这样做.

为确保您的测试不会乱七八糟,以下是一些入门指南:

--forbid-only

强制执行一个测试不能排他的规则(例如,禁止使用describe.only()it.only() ).

--forbid-only会导致Mocha在遇到排他("仅")测试或套件时失败,并将中止进一步的测试执行.

--forbid-pending

强制执行一项规则,即不得跳过测试this.skip()不允许在任何地方使用describe.skip()it.skip()this.skip() ).

--forbid-pending导致Mocha在遇到跳过的("待定")测试或套件时失败,并且将中止进一步的测试执行.

--global <variable-name>

在v6.0.0中更新; 该选项是--global--globals现在是别名.

定义一个全局变量名. 例如,假设您的应用故意公开了一个全局名称的appYUI ,则可能需要添加--global app --global YUI .

--global接受通配符. 您可以执行--global '*bar' ,它将与foobarbarbar等匹配.您也可以简单地传入'*'来忽略所有全局变量.

--global可以接受逗号分隔的列表; --global app,YUI等效于--global app --global YUI .

通过将此选项与--check-leaks结合使用,可以指定希望泄漏到全局范围内的已知全局变量白名单.

--retries <n>

重试失败的测试n次.

Mocha默认情况下不会重试测试失败.

--slow <ms>, -s <ms>

指定"慢速"测试阈值(以毫秒为单位). Mocha用它来突出显示耗时太长的测试用例. "慢速"测试不视为失败.

注意:执行"缓慢"时间一半的测试将使用默认的spec报告程序以黄色突出显示. 在整个"缓慢"时间内执行的测试将以红色突出显示.

--timeout <ms>, -t <ms>

v6.0.0中的更新: --no-timeout使用检查标志调用Mocha时,隐含--no-timeout . 等效于--timeout 0 . --timeout 99999999不再需要.

指定测试用例超时,默认为两(2)秒(2000毫秒). 花费时间超过此时间的测试将被标记为失败.

要覆盖你可以通过以毫秒为单位的超时,或与一个值s后缀,例如, --timeout 2s--timeout 2000是等价的.

要禁用超时,请使用--no-timeout .

注意:同步(阻塞)测试也受超时约束,但是直到代码停止阻塞后它们才能完成. 无限循环仍将是无限循环!

--ui <name>, -u <name>

The --ui option lets you specify the interface to use, defaulting to bdd.

--color, -c, --colors

在v6.0.0中更新. --colors现在是--color的别名.

启用"强制"颜色输出,或者通过--no-color强制禁用它. 默认情况下,Mocha使用supports-color模块来决定.

在某些情况下,某些报告程序以机器可读格式输出会显式抑制颜色输出.

--diff

如果可能,请声明遇到断言失败时的期望值与实际值之间的差异.

该标志是不寻常的,因为它默认为true . 使用--no-diff禁止Mocha自己的diff输出.

某些断言库将提供它们自己的差异,在这种情况下,无论默认值如何,都不会使用Mocha.

Mocha自己的差异输出不符合任何已知标准,并且被设计为易于阅读.

--full-trace

启用"完整"堆栈跟踪. 默认情况下,Mocha尝试将堆栈跟踪提炼为噪音较小(尽管仍然有用)的输出.

在调试Mocha或Node.js本身中的可疑问题时,此标志很有用.

--growl, -G

启用咆哮声 (或操作系统级别的通知,如果可用).

需要安装额外的软件; 有关更多信息,请参见咆哮模块的文档 .

--inline-diffs

启用"内联"差异,这是差异字符串的替代输出.

在处理大字符串时很有用.

如果断言库提供自己的diff输出,则不执行任何操作.

--reporter <name>, -R <name>

指定将要使用的报告程序,默认为spec .

允许使用第三方记者. 例如,安装后, mocha-lcov-reporter可以与--reporter mocha-lcov-reporter一起使用.

--reporter-option <option>, -O <option>, --reporter-options <option>

在v6.0.0中更新. 可以多次指定. --reporter-options现在是--reporter-option的别名.

<key>=<value>格式提供特定于报告--reporter tap --reporter-option tapVersion=13 ,例如--reporter tap --reporter-option tapVersion=13 .

并非所有的记者都接受选择.

可以指定为逗号分隔的列表.

--config <path>

New in v6.0.0.

指定配置文件的显式路径.

默认情况下,如果未指定--config ,则Mocha将搜索配置文件. 使用--no-config禁止此行为.

--opts <path>

Deprecated.

指定mocha.opts的路径.

默认情况下,摩卡寻找一个mocha.optstest/mocha.opts ; 使用--no-opts禁止这种行为.

--package <path>

v6.0.0中的新功能.

指定package.json文件的显式路径(表面上在mocha属性中包含配置).

默认情况下,Mocha在当前工作目录或最接近的祖先中查找package.json ,并将使用找到的第一个文件(无论它是否包含mocha属性); 要禁止package.json查找,请使用--no-package .

--extension <ext>

具有此扩展名的文件将被视为测试文件. 默认为js .

指定--extension删除 .js作为测试文件扩展名; 使用--extension js重新添加它. 例如,要加载.mjs.js测试文件,必须提供--extension mjs --extension js .

该选项可以多次给出. 该选项接受以逗号分隔的列表:-- --extension a,b等效于--extension a --extension b

--file <file|directory|glob>

Explicitly include a test file to be loaded before other test files. Multiple uses of --file are allowed, and will be loaded in order given.

例如,如果您想声明在所有其他测试文件的每次测试之前要运行的挂钩,则很有用.

以这种方式指定的文件不受--sort--recursive影响.

以这种方式指定的文件应包含一个或多个套件,测试或挂钩. 如果不是这种情况,请考虑--require .

--ignore <file|directory|glob>, --exclude <file|directory|glob>,

明确地忽略(排除)否则将要加载的一个或多个测试文件,目录或glob(例如some/**/files* ).

使用--file指定的文件不受此选项的影响 .

可以多次指定.

--recursive

查找测试文件时,请递归到子目录中.

有关定义哪些文件被视为测试文件,请参见--extension .

--require <module>, -r <module>

在加载用户界面或测试文件之前,需要一个模块. 这对于以下用途很有用:

期望以这种方式需要的模块可以同步工作. Mocha不会等待所需模块中的异步任务完成.

请注意,您不能使用--require来设置全局的beforeEach()挂钩,例如,使用--file代替,它允许您指定加载测试文件的显式顺序.

--sort, -S

使用Array.prototype.sort对测试文件进行排序(按绝对路径).

--watch, -w

重新测试文件更改.

--watch-files--watch-ignore选项可用于控制监视哪些文件的更改.

测试可以通过手动键入ⓡⓢ⏎(相同的快捷方式如重新运行nodemon ).

--watch-files <file|directory|glob>

v7.0.0的新功能

设置--watch时要监视的路径或--watch列表. 如果匹配给定glob的文件发生更改,或者添加或删除了mocha,mocha将重新运行所有测试.

如果路径是目录,则将监视所有文件和子目录.

By default all files in the current directory having one of the extensions provided by --extension and not contained in the node_modules or .git folders are watched.

该选项可以多次给出. 该选项接受以逗号分隔的列表:-- --watch-files a,b等效于--watch-files a --watch-files b

--watch-ignore <file|directory|glob>

v7.0.0的新功能

要排除在外的路径或全局列表. 默认为node_modules.git .

要排除目录中的所有文件,最好使用foo/bar而不是foo/bar/**/* . 后者仍将监视目录foo/bar但将忽略对该目录内容的所有更改.

该选项可以多次给出. 该选项接受以逗号分隔的列表:-- --watch-ignore a,b等效于--watch-ignore a --watch-ignore b

--fgrep <string>, -f <string>

v6.0.0中的BREAKING CHANGE; 现在与--grep .

使Mocha只运行标题包含给定string测试.

--grep .

--grep <regexp>, -g <regexp>

v6.0.0中的BREAKING CHANGE; 现在与--fgrep .

使Mocha只运行与给定regexp匹配的测试,该regexp在内部编译为RegExp .

例如,假设您具有与" api"相关的测试,以及与" app"相关的测试,如以下代码片段所示; 一个可以使用--grep api--grep app来运行其中一个. 套件或测试用例标题的任何其他部分也是如此,-- --grep users也将有效,甚至--grep GET也将有效.

describe('api', function() {
  describe('GET /api/users', function() {
    it('respond with an array of users', function() {
      // ...
    });
  });
});

describe('app', function() {
  describe('GET /users', function() {
    it('respond with an array of users', function() {
      // ...
    });
  });
});

--fgrep .

--invert

使用--grepfgrep指定的匹配项的倒数 .

需要--grep--fgrep (但不能同时使用).

--inspect, --inspect-brk, inspect

v7.0.0中的BREAKING CHANGE; --debug / --debug-brk已删除,并且不赞成使用debug .

启用Node.js的检查器.

使用--inspect / --inspect-brk启动用于Chrome开发工具的V8检查器.

使用inspect启动Node.js的内部调试器.

所有这些选项都是互斥的.

Implies --no-timeout.

About Option Types

在v6.0.0中更新.

在Mocha的--help输出中,每个标记为[boolean]类型的标志都可以通过在标志名称前--no-否定 . 例如,-- --no-color将禁用Mocha的颜色输出,默认情况下已启用.

除非另有说明,否则所有布尔标志均默认为false .

About node Flags

mocha可执行文件支持node可执行文件支持的所有适用标志.

这些标志根据您的Node.js版本而有所不同.

node标记可以在Mocha的配置中定义.

About V8 Flags

Prepend --v8- to any flag listed in the output of node --v8-options (excluding --v8-options itself) to use it.

可以在Mocha的配置中定义V8标志.

Interfaces

Mocha的"接口"系统使开发人员可以选择自己的DSL风格. Mocha具有BDDTDDExportsQUnitRequire样式的接口.

BDD

BDD接口提供describe() context() it() specify()before()after()beforeEach()afterEach()

context()只是describe()的别名, describe()行为方式相同; 它只是提供一种使测试更易于阅读和组织的方法. 类似地, specify()it()的别名.

所有先前的示例都是使用BDD接口编写的.

describe('Array', function() {
  before(function() {
    // ...
  });

  describe('#indexOf()', function() {
    context('when not present', function() {
      it('should not throw an error', function() {
        (function() {
          [1, 2, 3].indexOf(4);
        }.should.not.throw());
      });
      it('should return -1', function() {
        [1, 2, 3].indexOf(4).should.equal(-1);
      });
    });
    context('when present', function() {
      it('should return the index where the element first appears in the array', function() {
        [1, 2, 3].indexOf(3).should.equal(2);
      });
    });
  });
});

TDD

TDD接口提供suite()test()suiteSetup()suiteTeardown()setup()teardown()

suite('Array', function() {
  setup(function() {
    // ...
  });

  suite('#indexOf()', function() {
    test('should return -1 when not present', function() {
      assert.equal(-1, [1, 2, 3].indexOf(4));
    });
  });
});

Exports

Exports接口非常类似于Mocha的前身expresso . beforeafterbeforeEachafterEach是特殊情况,对象值是套件,函数值是测试用例:

module.exports = {
  before: function() {
    // ...
  },

  Array: {
    '#indexOf()': {
      'should return -1 when not present': function() {
        [1, 2, 3].indexOf(4).should.equal(-1);
      }
    }
  }
};

QUnit

QUnit启发的接口与QUnit的"扁平"外观相匹配,其中,测试套件标题仅在测试用例之前定义. 与TDD一样,它使用suite()test() ,但类似于BDD,它还包含before()after()beforeEach()afterEach() .

function ok(expr, msg) {
  if (!expr) throw new Error(msg);
}

suite('Array');

test('#length', function() {
  var arr = [1, 2, 3];
  ok(arr.length == 3);
});

test('#indexOf()', function() {
  var arr = [1, 2, 3];
  ok(arr.indexOf(1) == 0);
  ok(arr.indexOf(2) == 1);
  ok(arr.indexOf(3) == 2);
});

suite('String');

test('#length', function() {
  ok('foo'.length == 3);
});

Require

require界面使您可以直接使用requiredescribedescribe单词,并根据require调用它们. 如果要避免测试中使用全局变量,此接口也很有用.

注意require接口不能通过node可执行文件运行,而必须通过mocha运行.

var testCase = require('mocha').describe;
var pre = require('mocha').before;
var assertions = require('mocha').it;
var assert = require('chai').assert;

testCase('Array', function() {
  pre(function() {
    // ...
  });

  testCase('#indexOf()', function() {
    assertions('should return -1 when not present', function() {
      assert.equal([1, 2, 3].indexOf(4), -1);
    });
  });
});

Reporters

Mocha报告程序会调整到终端窗口,并在stdio流与TTY不关联时始终禁用ANSI转义颜色.

Spec

Alias: Spec, spec

这是默认的报告者. Spec报告程序输出与测试用例一样嵌套的层次结构视图.

spec reporter spec reporter with failure

Dot Matrix

Alias: Dot, dot

点矩阵报告器只是代表测试用例的一系列字符. 失败突显红色的感叹号( ! ),等待与蓝色逗号(测试, ),和缓慢的测试,黄色. 如果您更喜欢最小的输出,那就很好.

dot matrix reporter

Nyan

Alias: Nyan, nyan

Nyan记者正是您所期望的:

js nyan cat reporter

TAP

Alias: TAP, tap

TAP报告程序为Test-Anything-Protocol使用者发出行.

test anything protocol

Landing Strip

Alias: Landing, landing

Landing Strip记者是模仿飞机降落的:头测试记者:) unicode ftw

landing strip plane reporter landing strip with failure

List

Alias: List, list

当测试用例通过或失败时,列表报告器将输出一个简单的规格列表,并在输出的底部输出失败的详细信息.

list reporter

Progress

Alias: Progress, progress

进度报告器实现了一个简单的进度栏:

progress bar

JSON

Alias: JSON, json

测试完成(是否失败)后,JSON报告程序将输出一个大的JSON对象.

json reporter

JSON Stream

Alias: JSONStream, json-stream

JSON流报告器在发生时以换行分隔的JSON"事件"输出,从"开始"事件开始,然后是测试通过或失败,然后是最终的"结束"事件.

json stream reporter

Min

Alias: Min, min

Min报告器仅显示摘要,而失败时仍会输出错误. 该报告器与--watch配合使用非常好,因为它清除了终端,以便将测试摘要保持在顶部.

min reporter

Doc

Alias: Doc, doc

Doc报表器输出测试的分层HTML正文表示. 用页眉,页脚和某些样式包装它,然后您将获得一些很棒的文档!

doc reporter

例如,假设您具有以下JavaScript:

describe('Array', function() {
  describe('#indexOf()', function() {
    it('should return -1 when the value is not present', function() {
      [1, 2, 3].indexOf(5).should.equal(-1);
      [1, 2, 3].indexOf(0).should.equal(-1);
    });
  });
});

命令mocha --reporter doc array将产生:

<section class="suite">
  <h1>Array</h1>
  <dl>
    <section class="suite">
      <h1>#indexOf()</h1>
      <dl>
        <dt>should return -1 when the value is not present</dt>
        <dd>
          <pre><code>[1,2,3].indexOf(5).should.equal(-1);
[1,2,3].indexOf(0).should.equal(-1);</code></pre>
        </dd>
      </dl>
    </section>
  </dl>
</section>

SuperAgent请求库测试文档是使用以下Bash命令由Mocha的文档报告器生成的:

$ mocha --reporter=doc | cat docs/head.html - docs/tail.html > docs/test.html

查看SuperAgent的Makefile以供参考.

Markdown

Alias: Markdown, markdown

Markdown报告器为您的测试套件生成Markdown TOC和主体. 如果您想将测试用作Github Wiki页面中的文档或Github可以呈现的存储库中的markdown文件,那么这非常好. 例如,这是Connect 测试输出 .

XUnit

Alias: XUnit, xunit

XUnit报告器也可用. 它输出一个XUnit兼容的XML文档,通常适用于CI服务器.

默认情况下,它将输出到控制台. 要直接写入文件,请使用--reporter-option output=filename.xml .

要指定自定义报告标题,请使用--reporter-option suiteName="Custom name" .

Third-Party Reporters

Mocha允许您定义自定义报告器. 有关更多信息,请参见Wiki .

Examples:

HTML Reporter

Alias: HTML, html

HTML报告程序不适用于命令行.

Running Mocha in the Browser

Mocha在浏览器中运行. Mocha的每个发行版都将具有在浏览器中使用的./mocha.js./mocha.css新版本.

Browser-specific methods

以下方法在浏览器上下文中起作用:

mocha.allowUncaught() :如果调用,未捕获的错误将不会被错误处理程序吸收.

典型的设置可能类似于下面,我们称之为mocha.setup('bdd')加载测试脚本之前使用BDD界面,运行它们onloadmocha.run()

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Mocha Tests</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://unpkg.com/mocha/mocha.css" />
  </head>
  <body>
    <div id="mocha"></div>

    <script src="https://unpkg.com/chai/chai.js"></script>
    <script src="https://unpkg.com/mocha/mocha.js"></script>

    <script class="mocha-init">
      mocha.setup('bdd');
      mocha.checkLeaks();
    </script>
    <script src="test.array.js"></script>
    <script src="test.object.js"></script>
    <script src="test.xhr.js"></script>
    <script class="mocha-exec">
      mocha.run();
    </script>
  </body>
</html>

Grep

浏览器可能--grep用作功能. 将查询字符串追加到您的URL: ?grep=api .

Browser Configuration

可以通过mocha.setup()设置Mocha选项. 例子:

// Use "tdd" interface.  This is a shortcut to setting the interface;
// any other options must be passed via an object.
mocha.setup('tdd');

// This is equivalent to the above.
mocha.setup({
  ui: 'tdd'
});

// Use "tdd" interface, check global leaks, and force all tests to be asynchronous
mocha.setup({
  ui: 'tdd',
  checkLeaks: true,
  asyncOnly: true
});

Browser-specific Option(s)

浏览器Mocha支持许多(但不是全部) cli选项 .
要使用包含"-"的cli选项 ,请将选项转换为驼峰式(例如, check-leakscheckLeaks ).

Options that differ slightly from cli options:

reporter {string | constructor}
您可以传递报告者的姓名或自定义报告者的构造函数. 您可以在此处找到浏览器的推荐记者. 也可以使用内置的报告器 . 不建议也不支持在浏览器中使用它们,请打开控制台以查看测试结果.

Options that only function in browser context:

noHighlighting {boolean}
如果设置为true ,请不要尝试在输出测试代码上使用语法突出显示.

Reporting

在浏览器中运行Mocha时," html"报告程序是默认报告程序. 看起来像这样:

HTML test reporter

Mochawesome是默认HTML报告程序的绝佳替代方案.

Desktop Notification Support

桌面通知允许事件的异步通信,而不会强迫您立即响应通知. 它们的外观和特定功能因平台而异. 它们通常会在短暂的延迟后自动消失,但是它们的内容通常以允许您访问过去通知的某种方式存储.

Growl是针对OS X和Windows的早期通知系统实现,因此是Mocha的--growl选项的名称.

启用后,当根套件完成测试执行时,将出现一个桌面通知,通知您测试通过还是失败.

Node-based notifications

为了通过命令行界面(CLI)使用桌面通知,您必须首先安装某些特定于平台的必备软件. 有关说明,请参见此处 .

启用Mocha的桌面通知,如下所示:

$ mocha --growl

Browser-based notifications

Web通知支持可用于当前版本的现代浏览器. 确保您的浏览器版本同时支持PromiseWeb通知 . 随着Notification API随着时间的推移而发展, 不要期望最低的浏览器版本一定能正常工作.

稍加修改客户端Mocha HTML,即可启用Mocha的网络通知. 在运行测试之前,请添加对mocha.growl()的调用,如下所示:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Mocha Tests</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://unpkg.com/mocha/mocha.css" />
  </head>
  <body>
    <div id="mocha"></div>

    <script src="https://unpkg.com/chai/chai.js"></script>
    <script src="https://unpkg.com/mocha/mocha.js"></script>

    <script class="mocha-init">
      mocha.setup('bdd');
      mocha.growl(); // <-- Enables web notifications
    </script>
    <script src="test.spec.js"></script>
    <script class="mocha-exec">
      mocha.run();
    </script>
  </body>
</html>

Configuring Mocha (Node.js)

v6.0.0的新功能

In addition to supporting the deprecated mocha.opts run-control format, Mocha now supports configuration files, typical of modern command-line tools, in several formats:

Mocha建议使用上述策略之一进行配置,而不要使用不mocha.opts使用的mocha.opts格式.

Custom Locations

您可以使用--config <path>选项为配置文件指定自定义位置. Mocha将使用文件的扩展名来确定如何解析文件,如果未知,将采用JSON.

您也可以使用--package <path>选项指定自定义package.json位置.

Ignoring Config Files

要跳过寻找配置文件的过程,请使用--no-config . 同样,使用--no-package可以阻止Mocha在package.json寻找配置.

Priorities

如果未提供自定义路径,并且同一目录中有多个配置文件,则Mocha将仅搜索-并使用-一个. 优先级是:

  1. .mocharc.js
  2. .mocharc.yaml
  3. .mocharc.yml
  4. .mocharc.jsonc
  5. .mocharc.json

Merging

Mocha还将合并 package.json mocha.opts找到的所有选项到其运行时配置中. 如有冲突,优先级是:

  1. 在命令行上指定的参数
  2. 配置文件( .mocharc.js.mocharc.yml等)
  3. package.json mocha属性
  4. mocha.opts

可以安全地重复的选项(例如--require )将被串联起来--require较高的配置源将出现在列表的前面. 例如, .mocharc.json含有"require": "bar" ,再加上的执行mocha --require foo ,会导致摩卡要求foo ,然后bar ,在该顺序.

Extending Configuration

可以使用extends关键字从其他模块继承配置. 有关更多信息,请参见此处 .

Configuration Format

有关更多配置示例,请参阅GitHub上的example/config目录.

mocha.opts

mocha.opts文件支持已弃用,并将从以后的Mocha版本中删除. 我们建议改为使用配置文件.

Mocha将尝试加载"./test/mocha.opts"作为各种运行控制文件.

提供行首注释支持; 任何以井号( # )符号开头的行都将被视为注释. 也可以使用空行. 任何其他行都将被当作命令行参数(以及任何相关的选项值)用作默认设置. 设置应指定为每行一个.

此文件中的行位于任何实际的命令行参数之前. 这样,实际的命令行参数将优先于默认值.

例如,假设您具有以下mocha.opts文件:

# mocha.opts
  --require should
  --reporter dot
  --ui bdd

上面的设置将默认将报告程序设置为dot ,需要should库,并使用bdd作为界面. 这样,您就可以使用其他参数调用mocha ,在这里将报告者更改为list并将慢速阈值设置为半秒:

$ mocha --reporter list --slow 500

要忽略您的mocha.opts ,请使用--no-opts选项.

The test/ Directory

默认情况下, mocha查找"./test/*.js"全局"./test/*.js" ,因此您可能希望将测试放在test/文件夹中. 如果要包括子目录,请传递--recursive选项.

要配置mocha在哪里寻找测试,您可以通过自己的glob:

$ mocha --recursive "./spec/*.js"

某些外壳程序通过使用globstar( ** )通配符支持递归匹配. Bash> = 4.3通过globstar选项支持此功能必须启用它才能获得与传递--recursive选项相同的结果(默认情况下ZSHFish支持此功能). 启用递归匹配后,以下内容与传递--recursive相同:

$ mocha "./spec/**/*.js"

您应该始终在npm脚本中引用glob . 如果使用双引号,则是UNIX上的shell会扩展glob. 另一方面,如果使用单引号,则node-glob模块将处理其扩展.

请参阅有关使用glob的本教程 .

注意 :为了便于移植,建议在全局名称周围使用双引号.

Error Codes

v6.0.0的新功能

当Mocha本身引发异常时,关联的Error将具有code属性. 消费者应在适用的情况下检查code属性,而不是与message属性进行字符串匹配. 下表描述了这些错误代码:

CodeDescription
ERR_MOCHA_INVALID_ARG_TYPE给定参数传递了错误的类型
ERR_MOCHA_INVALID_ARG_VALUE给定参数传递了无效或不受支持的值
ERR_MOCHA_INVALID_EXCEPTION抛出了虚假的或未指定的异常
ERR_MOCHA_INVALID_INTERFACE找不到选项中指定的接口
ERR_MOCHA_INVALID_REPORTER找不到选项中指定的报告人
ERR_MOCHA_NO_FILES_MATCH_PATTERNtest file(s) could not be found
ERR_MOCHA_UNSUPPORTED请求的行为,选项或参数不受支持

Editor Plugins

提供了以下与编辑器相关的软件包:

TextMate

Mocha TextMate软件包包含一些片段,以使书写测试更快,更有趣.

JetBrains

JetBrains为其IDE套件(IntelliJ IDEA,WebStorm等)提供了NodeJS插件 ,其中包括Mocha测试运行程序.

JetBrains Mocha Runner Plugin in Action

该插件名为NodeJS ,可以在您的许可证允许的情况下通过"首选项" >" 插件"进行安装.

Wallaby.js

Wallaby.js是一个持续测试工具,可使用VS Code,Atom,JetBrains IDE(IntelliJ IDEA,WebStorm等),Sublime Text和Visual Studio中的任何断言库(适用于浏览器和节点)对Mocha进行实时代码覆盖. js项目.

Wallaby.js in Action

Emacs

可通过第三方软件包mocha.el获得Emacs对运行Mocha测试的支持. 该软件包在MELPA上可用,可以通过Mx package-install mocha .

Emacs Mocha Runner in Action

Mocha Sidebar (VS Code)

Mocha侧边栏是vs代码最完整的Mocha扩展.

Features

mocha side bar in Action

Examples

实际的示例代码:

Testing Mocha

要运行Mocha的测试,您将需要GNU Make或兼容版本. Cygwin应该工作.

$ cd /path/to/mocha
$ npm install
$ npm test

More Information

除了在Gitter上与我们聊天外,有关使用间谍,嘲笑和共享行为等其他信息,请确保查看GitHub上的Mocha Wiki . 如需讨论,请加入Google组 . 有关Mocha的运行示例,请查看example / tests.html . 对于JavaScript API,请查看API文档源代码 .

by  ICOPY.SITE