From 6fc0f1b99f364a8873719e06f0374dd0bff9f8a0 Mon Sep 17 00:00:00 2001
From: Gibson Fahnestock <gib@uk.ibm.com>
Date: Sat, 5 Nov 2016 12:59:35 +0000
Subject: [PATCH] doc: note that tests should include a description

Update the Writing Tests guide to specify that tests should include a
brief description of what they are designed to test.

PR-URL: https://github.com/nodejs/node/pull/9415

Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>oc
---
 doc/guides/writing_tests.md | 53 ++++++++++++++++++++++++-------------
 1 file changed, 34 insertions(+), 19 deletions(-)

diff --git a/doc/guides/writing_tests.md b/doc/guides/writing_tests.md
index 0e9d3a17cb3c51..169a9c8e5fa11f 100644
--- a/doc/guides/writing_tests.md
+++ b/doc/guides/writing_tests.md
@@ -23,23 +23,27 @@ Tests can be added for multiple reasons:
 Let's analyze this very basic test from the Node.js test suite:
 
 ```javascript
-1  'use strict'; 
-2  const common = require('../common');
-3  const http = require('http');
-4  const assert = require('assert');
-5
-6  const server = http.createServer(common.mustCall((req, res) => {
-7    res.end('ok');
-8  }));
-9  server.listen(0, () => {
-10   http.get({
-11     port: server.address().port,
-12     headers: {'Test': 'Düsseldorf'}
-13   }, common.mustCall((res) => {
-14     assert.equal(res.statusCode, 200);
-15     server.close();
-16   }));
-17 });
+1   'use strict';
+2   const common = require('../common');
+3
+4   // This test ensures that the http-parser can handle UTF-8 characters
+5   // in the http header.
+6
+7   const http = require('http');
+8   const assert = require('assert');
+9
+10  const server = http.createServer(common.mustCall((req, res) => {
+11    res.end('ok');
+12  }));
+13  server.listen(0, () => {
+14   http.get({
+15     port: server.address().port,
+16     headers: {'Test': 'Düsseldorf'}
+17   }, common.mustCall((res) => {
+18     assert.strictEqual(res.statusCode, 200);
+19     server.close();
+20   }));
+21 });
 ```
 
 **Lines 1-2**
@@ -60,7 +64,18 @@ require('../common');
 
 Why? It checks for leaks of globals.
 
-**Lines 3-4**
+**Lines 4-5**
+
+```javascript
+// This test ensures that the http-parser can handle UTF-8 characters
+// in the http header.
+```
+
+A test should start with a comment containing a brief description of what it is
+designed to test.
+
+
+**Lines 7-8**
 
 ```javascript
 const http = require('http');
@@ -72,7 +87,7 @@ modules should only include core modules.
 The `assert` module is used by most of the tests to check that the assumptions
 for the test are met.
 
-**Lines 6-17**
+**Lines 10-21**
 
 This is the body of the test. This test is quite simple, it just tests that an
 HTTP server accepts `non-ASCII` characters in the headers of an incoming