disableable assertions (#272)

state.js needs some assertions because it interfaces with parts of V8
debug API that are volatile across versions. However, we don't want to
be running these assertions in real user code. debug-assert module
allows us to run with assertions enabled in the CI.

PR-URL: #272

appveyor.yml

@@ -12,8 +12,8 @@ install:
   - ps: Install-Product node $env:nodejs_version
   # install modules
   - npm install
-  # set GCLOUD_PROJECT
   - SET GCLOUD_PROJECT=0
+  - SET CLOUD_DEBUG_ASSERTIONS=1
 
 # Post-install test scripts.
 test_script:

bin/run-test.sh

@@ -2,6 +2,9 @@
 
 # Usage: -c to report coverage
 
+# Enable assertions
+export CLOUD_DEBUG_ASSERTIONS=1
+
 while true; do
   case $1 in
     -c)

src/agent/debug-assert.js

@@ -0,0 +1,31 @@
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+'use strict';
+
+const realAssert = require('assert');
+
+const nop = _=>_;
+const fakeAssert = nop;
+fakeAssert.deepEqual = fakeAssert.deepStrictEqual = fakeAssert.doesNotThrow =
+    fakeAssert.equal = fakeAssert.fail = fakeAssert.ifError =
+    fakeAssert.notDeepEqual = fakeAssert.notDeepStrictEqual =
+    fakeAssert.notEqual = fakeAssert.notStrictEqual = fakeAssert.ok =
+    fakeAssert.strictEqual = fakeAssert.throws = 
+    fakeAssert.AssertionError = nop;
+
+module.exports = function debugAssert(enableAssertions) {
+  return enableAssertions ? realAssert : fakeAssert;
+};

src/agent/state.js

@@ -18,11 +18,12 @@
 
 module.exports = {
   capture: capture,
-  evaluate: evaluate
+  evaluate: evaluate,
+  testAssert: testAssert
 };
 
 var ScopeType = require('vm').runInDebugContext('ScopeType');
-var assert = require('assert');
+var assert = require('./debug-assert')(process.env.CLOUD_DEBUG_ASSERTIONS);
 var util = require('util');
 var lodash = require('lodash');
 var transform = lodash.transform;
@@ -518,3 +519,8 @@ StateResolver.prototype.resolveMirrorProperty_ = function(isEvaluated, property)
   }
   return this.resolveVariable_(name, property.value(), isEvaluated);
 };
+
+// This function is used by unit tests to make sure assertions are enabled.
+function testAssert() {
+  assert.equal(0, 1);
+}

test/test-debug-assert.js

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+'use strict';
+
+const realAssert = require('assert');
+
+describe('debug-assert', () => {
+  const debugAssert = require('../src/agent/debug-assert.js');
+
+  it('should fire assertions when enabled', () => {
+    realAssert.throws(() => {
+      const assert = debugAssert(true);
+      assert.equal(1, 2);
+    });
+  });
+
+  describe('disabled', () => {
+    const assert = debugAssert(false);
+
+    it('should not fire assertions when disabled', () => {
+      assert.equal(1, 2);
+    });
+
+    it('should cover the full assert API', () => {
+      Object.keys(realAssert).forEach((key) => {
+        realAssert.equal(typeof assert[key], 'function');
+      });
+    });
+  });
+});

test/test-state.js

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+'use strict';
+
+const assert = require('assert');
+const state = require('../src/agent/state.js');
+
+describe('state', () => {
+  // Testing of state.js is driven through test-v8debugapi.js. There are
+  // minimal unit tests here.
+
+  it('should have assertions enabled', () => {
+    // this test makes sure that the necessary environment variables to enable
+    // asserts are present during testing. Use run-tests.sh, or export
+    // CLOUD_DEBUG_ASSERTIONS=1 to make sure this test passes.
+    if (!process.env.CLOUD_DEBUG_ASSERTIONS) {
+      console.log('This test requires the enviornment variable ' + 
+                  'CLOUD_DEBUG_ASSERTIONS to be set in order to pass');
+    }
+    assert.throws(() => {
+      state.testAssert();
+    });
+  });
+});