docs(development.md): Add English translation

Add English translation for development.md.
eggjs · Feb 4, 2019 · 83c423a · 83c423a
1 parent d79da17
commit 83c423a
Showing 1 changed file with 339 additions and 1 deletion.
diff --git a/docs/source/en/core/development.md b/docs/source/en/core/development.md
@@ -1 +1,339 @@
-this document is still waiting for translation, see [Chinese Version](/zh-cn/core/development.html)
+title: Local Development
+---
+
+We provide convenient ways for development, debugging, and unit tests to improve your development experience.
+
+Here, wo will need to use [egg-bin] module (Only used in local development and unit tests. For production environment, please refer to [Deployment](./deployment.md)).
+
+First of all, we need to include `egg-bin` module in `devDependencies`:
+
+```bash
+$ npm i egg-bin --save-dev
+```
+
+## Start App
+
+Once we have modified code and saved in local development, the app will restart automatically, and our changes will take place right after that. 
+
+### Add Script
+
+Add `npm scripts` into `package.json`：
+
+```json
+{
+  "scripts": {
+    "dev": "egg-bin dev"
+  }
+}
+```
+
+And then we may start app by `npm run dev`.
+
+### Environment Configuration
+
+To start app in local, environment needs to be set as `env: local`. The configuration comes from the combination of both `config.local.js` and `config.default.js`.
+
+### Port Assignment
+
+Starting app in local will listen to port 7001 by default. You may assign other port to it like this:
+
+```json
+{
+  "scripts": {
+    "dev": "egg-bin dev --port 7001"
+  }
+}
+```
+
+## Unit Test
+
+Here we mainly cover the usage of the tools, for more details about unit tests, please refer to [here](./unittest.md).
+
+### Add Script
+
+Add `npm scripts` into `package.json`：
+
+```json
+{
+  "scripts": {
+    "test": "egg-bin test"
+  }
+}
+```
+
+And then we can run unit test by `npm test`.
+
+### Environment Configuration
+
+To run test cases, environment need to be set as `env: unittest`. The configuration comes from the combination of both `config.local.js` and `config.unittest.js`.
+
+### Run specific test file
+
+`npm test` command will look for all the files ended with `.test.js` under test folder (default [glob] matching rule is `test/**/*.test.js`).
+
+However, we would like to run only the test cases that we are working on sometimes. In this case, we may specify a file in the following way:
+
+```bash
+$ TESTS=test/x.test.js npm test
+```
+
+[glob] expressions are supported here.
+
+### Reporter setting
+
+Mocha supports various reporters. Default reporter is `spec`.
+
+Reporter is allowed to be specified mannually via setting TEST_REPORTER as the environment variable. For example, to use `dot` instead:
+
+```bash
+$ TEST_REPORTER=dot npm test
+```
+
+![image](https://cloud.githubusercontent.com/assets/156269/21849809/a6fe6df8-d842-11e6-8507-20da63bc8b62.png)
+
+### Timeout setting
+
+The default timeout is 30 seconds. We may set our own timeout (in milliseconds). For example, setting timeout to 5 seconds:
+
+```bash
+$ TEST_TIMEOUT=5000 npm test
+```
+
+### Pass Parameters Via argv
+
+Besides environment variables, `egg-bin test` also supports passing parameters directly, and it supports all mocha parameters. You may refer to [mocha usage](https://mochajs.org/#usage).
+
+```bash
+$ # Passing parameters via npm need to add an extra `--`, according to https://docs.npmjs.com/cli/run-script
+$ npm test -- --help
+$
+$ # Equivalent to `TESTS=test/**/test.js npm test`. Since the limitation of bash, it's better to add double qoute to path.
+$ npm test "test/**/test.js"
+$
+$ # Equivalent to `TEST_REPORTER=dot npm test`
+$ npm test -- --reporter=dot
+$
+$ # Parameters of mocha are supported, such as grep, require, etc.
+$ npm test -- -t 30000 --grep="should GET"
+```
+
+## Code Coverage
+
+egg-bin has build-in [nyc](https://github.com/istanbuljs/nyc) to support calculating code coverage report of unit test.
+
+Add `npm scripts` into `package.json`：
+
+```json
+{
+  "scripts": {
+    "cov": "egg-bin cov"
+  }
+}
+```
+
+And then we can get code coverage report of unit test via `npm run cov`.
+
+```bash
+$ egg-bin cov
+
+  test/controller/home.test.js
+    GET /
+      ✓ should status 200 and get the body
+    POST /post
+      ✓ should status 200 and get the request body
+
+  ...
+
+  16 passing (1s)
+
+=============================== Coverage summary ===============================
+Statements   : 100% ( 41/41 )
+Branches     : 87.5% ( 7/8 )
+Functions    : 100% ( 10/10 )
+Lines        : 100% ( 41/41 )
+================================================================================
+```
+
+And we may open HTML file of complete code coverage report via `open coverage/lcov-report/index.html`.
+
+![image](https://cloud.githubusercontent.com/assets/156269/21845201/a9a85ab6-d82c-11e6-8c24-5e85f352be4a.png)
+
+### Environment Configuration
+
+Just like test, the environment needs to be set to `env:unittest` to run cov, and the configuration comes from the combination of both `config.local.js` and `config.unittest.js`.
+
+### Ignore specific Files
+
+To ignore some files in code coverage rate calculation, You may use `COV_EXCLUDES` as the environment variable to ignore some specific files that don't need the test converages:
+
+```bash
+$ COV_EXCLUDES=app/plugins/c* npm run cov
+$ # Or pass this setting via parameters
+$ npm run cov -- --x=app/plugins/c*
+```
+
+## Debugging
+
+### Log Print
+
+### Use `Logger` Module
+
+There's a built-in [Log](./logger.md) in the egg, so you may use logger.debug() to print out debug information. **We recommend you use it in your own code.**
+
+```js
+// controller
+this.logger.debug('current user: %j', this.user);
+
+// service
+this.ctx.logger.debug('debug info from service');
+
+// app/init.js
+app.logger.debug('app init');
+```
+
+Levels of logs can be configured via `config.logger.level` for printing into file, and `config.logger.consoleLevel` for printing into console.
+
+### Use `Debug` Module
+
+[debug](https://www.npmjs.com/package/debug) module is a debug tool widely adopted in Node.js community, plenty of modules are using it to print debug information. So for the Egg community. **We recommand you use it in your own development of framework and plugins.**
+
+It's easy for us to watch the whole process of test through `DEBUG` as the environment variable to start with certain code.
+
+(Do not confuse debug module with logger module, for the latter also has quite a lot of functions, what we mean "log" here is the debug info.)
+
+Turn on log of all modules:
+
+```bash
+$ DEBUG=* npm run dev
+```
+
+Turn on log of specific module:
+
+```bash
+$ DEBUG=egg* npm run dev
+```
+
+Detail logs of unit tests progress are able to be viewed via `DEBUG=* npm test`.
+
+### Debug With egg-bin
+
+#### Add Script
+
+Add `npm scripts` into `package.json`：
+
+```json
+{
+  "scripts": {
+    "debug": "egg-bin debug"
+  }
+}
+```
+
+And then we may set breakpoints for debugging our app via `npm run debug`.
+
+`egg-bin` will select debug protocol automatically. [Inspector Protocol] will be selected for version 8.x and later. For earlier ones, [Legacy Protocol] is the choice.
+
+In the meantime, It also supports customized debug parameters.
+
+```bash
+$ egg-bin debug --inpsect=9229
+```
+
+- Debug port of `master` is 9229 or 5858 (Legacy Protocol).
+- Debug port of `agent` is fixed to 5800, it is customizable via `process.env.EGG_AGENT_DEBUG_PORT`.
+- Debug port number of `worker` will increase from `master` port number.
+- During developing period, worker will "hot restart" once the code is changed, and it will cause the increase of port. Please refer to the following IDE configuration for auto-reconnecting.
+
+#### Environment Configuration
+
+App starts by `env: local` when executing debug . The configuration comes from the combination of both `config.local.js` and `config.unittest.js`.
+
+#### Debug With [DevTools] 
+
+The latest DevTools only supports [Inspector Protocol]. Thus you will need to install Node.js 8.x or higher verions to be able to use it.
+
+Execute `npm run debug` to start it:
+
+```bash
+➜  showcase git:(master) ✗ npm run debug
+
+> [email protected] debug /Users/tz/Workspaces/eggjs/test/showcase
+> egg-bin debug
+
+Debugger listening on ws://127.0.0.1:9229/f8258ca6-d5ac-467d-bbb1-03f59bcce85b
+For help see https://nodejs.org/en/docs/inspector
+2017-09-14 16:01:35,990 INFO 39940 [master] egg version 1.8.0
+Debugger listening on ws://127.0.0.1:5800/bfe1bf6a-2be5-4568-ac7d-69935e0867fa
+For help see https://nodejs.org/en/docs/inspector
+2017-09-14 16:01:36,432 INFO 39940 [master] agent_worker#1:39941 started (434ms)
+Debugger listening on ws://127.0.0.1:9230/2fcf4208-4571-4968-9da0-0863ab9f98ae
+For help see https://nodejs.org/en/docs/inspector
+9230 opened
+Debug Proxy online, now you could attach to 9999 without worry about reload.
+DevTools → chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9999/__ws_proxy__
+```
+
+And then choose one of the following ways:
+- Visit the `DevTools` URL printed in the last few lines in console directly. Since this URL is proxied from worker, you don't need to worry about restarting.
+- Open `chrome://inspect`, and config port accordingly, then click `Open dedicated DevTools for Node` to open debug console.
+
+![DevTools](https://user-images.githubusercontent.com/227713/30419047-a54ac592-9967-11e7-8a05-5dbb82088487.png)
+
+#### Debug With WebStorm
+
+`egg-bin` will read environment variable `$NODE_DEBUG_OPTION` set in WebStorm debug mode.
+
+Start npm debug in WebStorm：
+
+![WebStorm](https://user-images.githubusercontent.com/227713/30423086-5dd32ac6-9974-11e7-840f-904e49a97694.png)
+
+#### Debug With [VSCode]
+
+There are 2 ways:
+
+1st method: open settings in VSCode, turn on `Debug: Toggle Auto Attach`, and then execute `npm run debug` in the terminal.
+
+2nd method: setup `.vscode/launch.json` in VSCode, and then simply start with F5 key. (Note: You have to turn off the settings mentioned in the 1st method before doing it).
+
+```js
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Launch Egg",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceRoot}",
+      "runtimeExecutable": "npm",
+      "windows": { "runtimeExecutable": "npm.cmd" },
+      "runtimeArgs": [ "run", "debug", "--", "--inspect-brk" ],
+      "console": "integratedTerminal",
+      "protocol": "auto",
+      "restart": true,
+      "port": 9229,
+      "autoAttachChildProcesses": true
+    }
+  ]
+}
+```
+
+And we offer a [vscode-eggjs] extention to setup auto-matically.
+
+![VSCode](https://user-images.githubusercontent.com/227713/35954428-7f8768ee-0cc4-11e8-90b2-67e623594fa1.png)
+
+
+For more options of setting up debug in VSCode, please refer to [Node.js Debugging in VS Code](https://code.visualstudio.com/docs/nodejs/nodejs-debugging).
+
+## More
+
+If you would like to know more about local development, like customizing a local development tool for your team, please refer to [egg-bin].
+
+[glob]: https://www.npmjs.com/package/glob
+[egg-bin]: https://github.com/eggjs/egg-bin
+[VSCode]: https://code.visualstudio.com
+[Legacy Protocol]: https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md
+[Inspector Protocol]: https://chromedevtools.github.io/debugger-protocol-viewer/v8
+[DevTools]: https://developer.chrome.com/devtools
+[WebStorm]: https://www.jetbrains.com/webstorm/
+[vscode-eggjs]: https://github.com/eggjs/vscode-eggjs