From 7d117da762fe170b85a3154bd58a401304fbc53b Mon Sep 17 00:00:00 2001
From: Kelvin Jin <kelvinjin@google.com>
Date: Thu, 18 Jan 2018 10:47:39 -0800
Subject: [PATCH 1/2] doc: add details about running tests locally in
 CONTRIBUTING.md

---
 CONTRIBUTING.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0e104db5e..adcc420a0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,3 +1,50 @@
+# Building and Running Tests Locally
+
+To ensure that the Trace Agent works cross-platform, we use TypeScript build scripts located in the [`scripts`](scripts) directory. The entry point to these scripts is [`index.ts`](scripts/index.ts). The usage of this file is `ts-node -p ./scripts ./scripts/index.ts [command1] [...moreCommands]` (assuming that you are running in the repository root directory.)
+
+The list of possible build commands is enumerated as `case` statements in `index.ts`, in addition to `npm-*` commands. See [`index.ts`](scripts/index.ts) for more details.
+
+`npm run script` is an alias for `ts-node -p ./scripts ./scripts/index.ts`.
+
+For example, to compile all scripts and then initialize test fixtures, the command to use would be one of:
+
+```bash
+# Option 1
+ts-node -p ./scripts ./scripts/index.ts npm-compile-all init-test-fixtures
+
+# Option 2
+npm run script npm-compile-all init-test-fixtures
+
+# Option 3
+npm run compile-all
+npm run script init-test-fixtures
+```
+
+They are equivalent.
+
+## Unit Tests
+
+The minimum list of commands needed to run unit tests are:
+
+```bash
+npm install
+export GCLOUD_TRACE_NEW_CONTEXT=1 # This is required. See cloud-trace-nodejs #650
+npm run compile
+npm run init-test-fixtures
+npm test # Or "npm run script run-unit-tests"
+```
+
+A convenient one-liner for this (after `npm install`) is:
+
+```bash
+npm install
+GCLOUD_TRACE_NEW_CONTEXT=1 npm run script npm-compile-all init-test-fixtures run-unit-tests
+```
+
+### Why `init-test-fixtures`
+
+The Trace Agent unit tests rely on installing traced modules fixed at distinct version ranges. See [`plugin-fixtures.json`](test/fixtures/plugin-fixtures.json) for the list of fixtures.
+
 # How to become a contributor and submit your own code
 
 ## Contributor License Agreements

From f0e6ecb334187cb28c52af7a7ed09353b86f4ef9 Mon Sep 17 00:00:00 2001
From: Kelvin Jin <kelvinjin@google.com>
Date: Thu, 18 Jan 2018 11:34:57 -0800
Subject: [PATCH 2/2] Update CONTRIBUTING.md

---
 CONTRIBUTING.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index adcc420a0..80b97a0da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,6 +41,8 @@ npm install
 GCLOUD_TRACE_NEW_CONTEXT=1 npm run script npm-compile-all init-test-fixtures run-unit-tests
 ```
 
+You will need to have mysql, postgres, redis, and mongo instances listening on their corresponding canonical ports. When running locally, you can use `./bin/docker-trace.sh start` to start docker images that does this for you.
+
 ### Why `init-test-fixtures`
 
 The Trace Agent unit tests rely on installing traced modules fixed at distinct version ranges. See [`plugin-fixtures.json`](test/fixtures/plugin-fixtures.json) for the list of fixtures.