doc: add watch-mode and when to use plan translate

zhaozhiming · zhaozhiming · commit 176dc4437a1b · 2016-03-20T20:43:35.000+08:00
diff --git a/zh_CN/docs/recipes/watch-mode.md b/zh_CN/docs/recipes/watch-mode.md
@@ -0,0 +1,107 @@
+___
+**备注**
+
+这是[watch-mode.md](https://github.com/sindresorhus/ava/blob/master/docs/recipes/watch-mode.md)的简体中文翻译。这个[链接](https://github.com/sindresorhus/ava/compare/master...zhaozhiming:master)用来查看本翻译与AVA的master分支是否有差别（如果你没有看到`watch-mode.md`发生变化，那就意味着这份翻译文档是最新的）。
+___
+
+# 观察模式
+
+翻译: [Français](https://github.com/sindresorhus/ava-docs/blob/master/fr_FR/docs/recipes/watch-mode.md), [Русский](https://github.com/sindresorhus/ava-docs/blob/master/ru_RU/docs/recipes/watch-mode.md), [简体中文](https://github.com/sindresorhus/ava-docs/blob/master/zh_CN/docs/recipes/watch-mode.md)
+
+
+AVA自带了一个聪明的观察模式，它会观察那些改变了的文件并运行受到改变影响的测试。
+
+## 运行测试时启用观察模式
+
+你可以通过使用`--watch`或`-w`标志来启用观察模式，如果你是全局安装的AVA：
+
+```console
+$ ava --watch
+```
+
+如果你将AVA配置在`package.json`中，像这样：
+
+```json
+{
+  "scripts": {
+    "test": "ava"
+  }
+}
+```
+
+你可以这样运行：
+
+```console
+$ npm test -- --watch
+```
+
+你可以设置一个特殊的脚本：
+
+```json
+{
+  "scripts": {
+    "test": "ava",
+    "test:watch": "ava --watch"
+  }
+}
+```
+
+然后使用：
+
+```console
+$ npm run test:watch
+```
+
+## 要求
+
+AVA使用[`chokidar`]来作为文件观察期，它被配置为可选的依赖，因为`chokidar`有时候无法安装，如果`chokidar`安装失败那么观察模式就不可用，然后你将看到一条这样的信息：
+
+> The optional dependency chokidar failed to install and is required for --watch. Chokidar is likely not supported on your platform.
+
+请参考[`chokidar`文档][`chokidar`]了解如何解决这个问题。
+
+## 源文件和测试文件
+
+在AVA中*源文件*和*测试文件*是有差别的，正如你所想的一样，*测试文件*包含了你的测试，*源文件*是需要支持测试运行的
+其他所有文件，是你的源代码或者测试数据。
+
+默认情况下AVA观察测试文件，`package.json`和其他的`.js`文件的改变，它会忽略由[`ignore-by-default`]包提供的[特定文件夹](https://github.com/novemberborn/ignore-by-default/blob/master/index.js)下的文件。
+
+你可以使用[`--source` CLI 标志]或`package.json`文件的`ava`属性为源文件配置模式，注意如果你从[`ignore-by-default`]中指定了一个负模式目录，那么忽略将不再有效，所以你可能想要在你的配置里重复这些操作。
+
+如果你的测试会写入磁盘，那么它们会跟踪观察器来返回你的测试，这种情况下你需要使用`--source`标志。
+
+## 依赖跟踪
+
+AVA跟踪测试文件依赖的源文件，如果你改变的源文件只有一个测试依赖那么久只会返回这个测试，如果它不能识别哪个测试文件依赖了这个被修改的源文件，那么它会返回所有的测试。
+
+依赖跟踪在required模式中有效，支持自定义继承和转换，使用[`--require` CLI标志]而不是从你的测试文件来帮助你加载它们。使用`fs`模块来做的文件访问不会被跟踪。
+
+## 手动返回所有测试
+
+你可以在console中，通过在<kbd>Enter</kbd>后面打印<kbd>r</kbd>来快速返回所有测试，
+
+## 调试
+
+有时候观察模式会出现一些意想不到的事情，比如当你只运行一个测试时会返回所有测试，为了调查原因你可以启用调试模式：
+
+```console
+$ DEBUG=ava:watcher npm test -- --watch
+```
+
+在Windows里这样用：
+
+```console
+$ set DEBUG=ava:watcher
+$ npm test -- --watch
+```
+
+## 帮助我们改善观察模式
+
+观察模式比较新并且现在处于初期阶段，请[报告](https://github.com/sindresorhus/ava/issues)任何你遇到问题，谢谢！
+
+[`chokidar`]: https://github.com/paulmillr/chokidar
+[`ignore-by-default`]: https://github.com/novemberborn/ignore-by-default
+[`--require` CLI 标志]: https://github.com/sindresorhus/ava#cli
+[`--source` CLI 标志]: https://github.com/sindresorhus/ava#cli
+
diff --git a/zh_CN/docs/recipes/when-to-use-plan.md b/zh_CN/docs/recipes/when-to-use-plan.md
@@ -0,0 +1,140 @@
+___
+**备注**
+
+这是[when-to-use-plan.md](https://github.com/sindresorhus/ava/blob/master/docs/recipes/when-to-use-plan.md)的简体中文翻译。这个[链接](https://github.com/sindresorhus/ava/compare/master...zhaozhiming:master)用来查看本翻译与AVA的master分支是否有差别（如果你没有看到`when-to-use-plan.md`发生变化，那就意味着这份翻译文档是最新的）。
+___
+
+# 什么时候使用`t.plan()`
+
+翻译: [Español](https://github.com/sindresorhus/ava-docs/blob/master/es_ES/docs/recipes/when-to-use-plan.md), [Français](https://github.com/sindresorhus/ava-docs/blob/master/fr_FR/docs/recipes/when-to-use-plan.md), [日本語](https://github.com/sindresorhus/ava-docs/blob/master/ja_JP/docs/recipes/when-to-use-plan.md),  [Português](https://github.com/sindresorhus/ava-docs/blob/master/pt_BR/docs/recipes/when-to-use-plan.md), [Русский](https://github.com/sindresorhus/ava-docs/blob/master/ru_RU/docs/recipes/when-to-use-plan.md), [简体中文](https://github.com/sindresorhus/ava-docs/blob/master/zh_CN/docs/recipes/when-to-use-plan.md)
+
+AVA和[`tap`](https://github.com/tapjs/node-tap)/[`tape`](https://github.com/substack/tape)的一个主要不同是`t.plan()`的行为。在AVA中`t.plan()`只是用来断言期望的断言数是否正确，并不会自动结束测试。
+
+## `t.plan()`不好的用法
+
+很多从`tap/tape`过渡过来的用户习惯在每个测试里大量使用`t.plan()`，尽管如此，在AVA里我们不认为这是一个“最佳实践”，我们反而认为`t.plan()`只有在少数情况才能提供其价值。
+
+### 没有分支的同步测试
+
+在大部分同步测试中`t.plan()`是没有必要的。
+
+```js
+test(t => {
+    // 不好：这里没有分支，t.plan是无意义的
+    t.plan(2);
+
+    t.is(1 + 1, 2);
+    t.is(2 + 2, 4);
+});
+```
+
+`t.plan()`在这里并没有提供任何价值，并且如果你决定添加或删除断言时会带来额外的工作。
+
+### Promises期望得到resolve
+
+```js
+test(t => {
+    t.plan(1);
+
+    return somePromise().then(result => {
+        t.is(result, 'foo');
+    });
+});
+```
+
+简单看一下，这个测试充分利用了`t.plan()`的优势，因为这里面涉及到了异步promise处理。尽管如此在这个测试里还有一些问题：
+
+1. `t.plan()`用在这里大概是为了防止`somePromise()`可能被reject的情况，但返回一个reject的promise测试始终会失败。
+
+2. 使用`async`/`await`可能会更好。
+
+```js
+test(async t => {
+    t.is(await somePromise(), 'foo');
+});
+```
+
+## `t.plan()`好的用法
+
+`t.plan()`有很多可接受的用法。
+
+### Promise带上一个`.catch()`块
+
+```js
+test(t => {
+    t.plan(2);
+
+    return shouldRejectWithFoo().catch(reason => {
+        t.is(reason.message, 'Hello') // 如果你关心的是message的话使用t.throws()更好
+        t.is(reason.foo, 'bar');
+    });
+});
+```
+
+在这里，`t.plan()`用来确保`catch`块中的代码被执行，在大部分情况下，你更应该使用`t.throws()`断言，但这是一个可以接受的用法，因为`t.throws()`只允许你断言错误的`message`属性。
+
+### 确保一个catch语句发生
+
+```js
+test(t => {
+    t.plan(2);
+
+    try {
+        shouldThrow();
+    } catch (err) {
+        t.is(err.message, 'Hello') // 如果你关心的是message的话使用t.throws()更好
+        t.is(err.foo, 'bar');
+    }
+});
+```
+
+像上面这种`try`/`catch`的情况，使用`t.throws()`一般是个更好的选择，但它只允许你断言错误的`message`属性。
+
+### 确保多个callback被真正调用
+
+```js
+test.cb(t => {
+    t.plan(2);
+
+    const callbackA = () => {
+        t.pass();
+        t.end();
+    };
+
+    const callbackB = () => t.pass();
+
+    bThenA(callbackA, callbackB);
+});
+```
+
+上面确保`callbackB`先被调用（且只调用一次），紧接着调用`callbackA`，其他的组合不会满足计划。
+
+### 测试带有分支语句
+
+在大部分情况下，在测试中使用复杂的分支是一个坏主意，一个明显的例外是用来测试自动生成的东西（可能来自一个JSON文档）。下面的`t.plan()`用来确保JSON输入的正确性：
+
+```js
+const testData = require('./fixtures/test-definitions.json');
+
+testData.forEach(testDefinition => {
+    test(t => {
+        const result = functionUnderTest(testDefinition.input);
+
+        // testDefinition应该有一个`foo`或`bar`的预期而不是同时满足它们 
+        t.plan(1);
+
+        if (testDefinition.foo) {
+            t.is(result.foo, testDefinition.foo);
+        }
+
+        if (testDefinition.bar) {
+            t.is(result.bar, testDefinition.foo);
+        }
+    });
+});
+```
+
+## 总结
+
+`t.plan()`有很多有效的使用方法，但不应该被盲目使用。一个好的经验法则是你的*测试*没有简单的，容易推断的，代码流你可以使用它。测试在callback里带有断言，`if`/`then`语句，`for`/`while`循环，并且（在一些情况下）`try`/`catch`块，都可以考虑使用`t.plan()`。
+
diff --git a/zh_CN/readme.md b/zh_CN/readme.md
@@ -904,9 +904,9 @@ AVA，不是Ava，也不是ava，发音[`/ˈeɪvə/` ay-və](https://github.com/
 ## 秘方 
 
 - [代码覆盖率](docs/recipes/code-coverage.md)
-- [观察模式](https://github.com/sindresorhus/ava/blob/master/docs/recipes/watch-mode.md)
+- [观察模式](docs/recipes/watch-mode.md)
 - [端点测试](docs/recipes/endpoint-testing.md)
-- [什么时候使用`t.plan()`](https://github.com/sindresorhus/ava/blob/master/docs/recipes/when-to-use-plan.md)
+- [什么时候使用`t.plan()`](docs/recipes/when-to-use-plan.md)
 - [浏览器测试](docs/recipes/browser-testing.md)
 - [TypeScript](docs/recipes/typescript.md)
 
