From 75f0855f4cccc8c806a0c165ece1e6651e03765c Mon Sep 17 00:00:00 2001
From: Daniel Bevenius <daniel.bevenius@gmail.com>
Date: Fri, 24 Mar 2017 15:45:46 +0100
Subject: [PATCH] doc: c++ unit test guide lines

PR-URL: https://github.com/nodejs/node/pull/11956
Ref: https://github.com/nodejs/node/pull/9163
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/guides/writing-tests.md | 62 +++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md
index 4f226bfdb2580c..d0a6e1a1995ebb 100644
--- a/doc/guides/writing-tests.md
+++ b/doc/guides/writing-tests.md
@@ -279,3 +279,65 @@ If you want to improve tests that have been imported this way, please send
 a PR to the upstream project first. When your proposed change is merged in
 the upstream project, send another PR here to update Node.js accordingly.
 Be sure to update the hash in the URL following `WPT Refs:`.
+
+## C++ Unit test
+C++ code can be tested using [Google Test][]. Most features in Node.js can be
+tested using the methods described previously in this document. But there are
+cases where these might not be enough, for example writing code for Node.js
+that will only be called when Node.js is embedded.
+
+### Adding a new test
+The unit test should be placed in `test/cctest` and be named with the prefix
+`test` followed by the name of unit being tested. For example, the code below
+would be placed in `test/cctest/test_env.cc`:
+
+```c++
+#include "gtest/gtest.h"
+#include "node_test_fixture.h"
+#include "env.h"
+#include "node.h"
+#include "v8.h"
+
+static bool called_cb = false;
+static void at_exit_callback(void* arg);
+
+class EnvTest : public NodeTestFixture { };
+
+TEST_F(EnvTest, RunAtExit) {
+  v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = v8::Context::New(isolate_);
+  node::IsolateData* isolateData = node::CreateIsolateData(isolate_, uv_default_loop());
+  Argv argv{"node", "-e", ";"};
+  auto env = Environment:CreateEnvironment(isolateData, context, 1, *argv, 2, *argv);
+  node::AtExit(at_exit_callback);
+  node::RunAtExit(env);
+  EXPECT_TRUE(called_cb);
+}
+
+static void at_exit_callback(void* arg) {
+  called_cb = true;
+}
+```
+
+Next add the test to the `sources` in the `cctest` target in node.gyp:
+```
+'sources': [
+  'test/cctest/test_env.cc',
+  ...
+],
+```
+The test can be executed by running the `cctest` target:
+```
+$ make cctest
+```
+
+### Node test fixture
+There is a [test fixture] named `node_test_fixture.h` which can be included by
+unit tests. The fixture takes care of setting up the Node.js environment
+and tearing it down after the tests have finished.
+
+It also contains a helper to create arguments to be passed into Node.js. It
+will depend on what is being tested if this is required or not.
+
+[Google Test]: https://github.com/google/googletest
+[Test fixture]: https://github.com/google/googletest/blob/master/googletest/docs/Primer.md#test-fixtures-using-the-same-data-configuration-for-multiple-tests