Verify @example docs on npm test #627

ryanseys · 2015-05-25T21:12:17Z

Fixes #598
Fixes #622
Fixes #623

I really wanted to build this because it seemed like an interesting problem and this builds on our already-epic docs to make them more epic.

This adds an additional test which will run with npm test like normal, though I would suggest we consider changing npm test to also generate docs, then run the tests to ensure the test remains up to date with the docs generated.

The idea is that we read in docs/**/*.json files and iterate through every appropriate @example tag, extract the code string, and run it inside a node.js vm sandbox, ensuring that it doesn't throw an error along the way. This means that it will check for general syntax errors, as well as calling methods with the wrong number of parameters or missing parameters or just plain incorrect parameters.

A lot of this PR is cleaning up the docs so the test passes! Yeah, it caught a wide range of issues! 👍

One thing to note is that it has no way of running anything asynchronously or waiting in anyway for any async function to be called in the VM because we'd have to then inject our own code into the existing examples and that would be quite difficult to guess.

For example Dataset#runInTransaction (which you'll see a lot of in this PR) actually is an async function and so it makes it impossible to test anything that is included in the callback of that function, and unfortunately the only way we recommend they create a transaction object is by running dataset.runInTransaction() so I'm not sure what we should do to mitigate this issue and test our transaction object. I'll comment on the PR where this issue takes place.

lib/datastore/request.js

 *     numDonutsServed: 45, // detect number type (int or double)
- *     founded: new Date('Tue May 12 2015 15:30:00 GMT-0400 (EDT)'), // dates
+ *     // founded: new Date('Tue May 12 2015 15:30:00 GMT-0400 (EDT)'), // dates


jgeewax · 2015-05-26T01:17:57Z

This is awesome. I totally get it that we can't inspect inside callbacks... maybe there's some magic we can figure out later, but for now this is a huge step forward. 👍

stephenplusplus · 2015-05-26T01:41:55Z

This is amazing. This is the first time I've seen anything like this in OSS/ever. @jgeewax is there some kind of Google Dev Blog we can write about this on after it's merged?

lib/datastore/transaction.js

- *     // Commit the transaction.
- *     transaction.finalize(function(err, apiResponse) {});
+ * dataset.runInTransaction(function(transaction, done) {
+ *   transaction.begin(function(err) {


ryanseys · 2015-05-26T14:04:33Z

Adding so I can continue working on this today to investigate mitigating some of the issues I've made apparent here with the current version.

ryanseys · 2015-05-26T15:16:35Z

Whoa! This docs test found a real live bug! Our transaction#rollback didn't attach the transaction id like it should have. I added a unit test to catch it :)

lib/datastore/transaction.js

@@ -143,10 +141,10 @@ Transaction.prototype.rollback = function(callback) {
 * Commit the remote transaction and finalize the current transaction instance.
 *
 * @param {function} callback - The callback function.
+ * @private


stephenplusplus · 2015-05-26T15:24:31Z

Whoa! This docs test found a real live bug! Our transaction#rollback didn't attach the transaction id like it should have. I added a unit test to catch it :)

Nice!

ryanseys · 2015-05-27T16:08:43Z

PTAL. Should test all our examples, including ignored and private ones.
Also privatized Transaction#begin_ and Transaction#commit_.

test/common/docs.js

+  });
+
+  it('should run docs examples without errors', function() {
+    for (var f in FILES) {


stephenplusplus · 2015-05-27T16:29:35Z

This isn't a problem in this PR, but I just discovered something I must have messed up before:

https://github.com/ryanseys/gcloud-node/blob/72dc556b8911972fe6afdd1aec9fe4e774d4cc27/lib/datastore/transaction.js#L266

Those examples shouldn't show delete taking a callback. Feel free to fix while you're in there, or I can always get to it after.

test/common/docs.js

+        ].join('\n'));
+      }
+
+      var sandbox = {


lib/datastore/dataset.js

+ * perform multiple operations, committing your changes atomically. When you are
+ * finished making your changes within the transaction, run the done() function
+ * provided in the callback function to commit your changes. See an example
+ * below for more information.


stephenplusplus · 2015-05-29T19:10:20Z

This is awesome. You made history.

@example

Verify @example docs on npm test

ryanseys · 2015-05-29T19:20:00Z

Yay! This thing is awesome! :) I'm excited to see it break our builds with no remorse.

* feat: Add SavedQuery CURD support feat: Add tags support feat!：*Add RelatedAsset and deprecate RelatedAssets for relationship GA *The previous representation of the relationship feature is deprecated and unimplemented. The RelatedAsset message represents the new stable format. PiperOrigin-RevId: 449306805 Source-Link: googleapis/googleapis@3d7bd9d Source-Link: googleapis/googleapis-gen@71a93d0 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNzFhOTNkMDVkNjA3NjI3MWQwNGI3NTkyZjdmYWQwZDNmMGM3YTA0MCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

- [ ] Regenerate this pull request now. PiperOrigin-RevId: 474338479 Source-Link: googleapis/googleapis@d5d35e0 Source-Link: googleapis/googleapis-gen@efcd3f9 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZWZjZDNmOTM5NjJhMTAzZjY4ZjAwM2UyYTFlZWNkZTZmYTIxNmEyNyJ9

🤖 I have created a release *beep* *boop* --- ## [4.1.0](googleapis/nodejs-dataproc@v4.0.1...v4.1.0) (2022-09-22) ### Features * Add support for Dataproc metric configuration ([#626](googleapis/nodejs-dataproc#626)) ([79a4958](googleapis/nodejs-dataproc@79a4958)) * Support regapic LRO ([350626e](googleapis/nodejs-dataproc@350626e)) ### Bug Fixes * Allow passing gax instance to client constructor ([#612](googleapis/nodejs-dataproc#612)) ([caba80a](googleapis/nodejs-dataproc@caba80a)) * **deps:** Do not depend on protobufjs ([#607](googleapis/nodejs-dataproc#607)) ([4b62ef6](googleapis/nodejs-dataproc@4b62ef6)) * **deps:** Roll back dependency @google-cloud/dataproc to ^4.0.0 ([#627](googleapis/nodejs-dataproc#627)) ([e1c6d8b](googleapis/nodejs-dataproc@e1c6d8b)) * Do not import the whole google-gax from proto JS ([#1553](https://github.com/googleapis/nodejs-dataproc/issues/1553)) ([#617](googleapis/nodejs-dataproc#617)) ([2e2bea1](googleapis/nodejs-dataproc@2e2bea1)) * Preserve default values in x-goog-request-params header ([#620](googleapis/nodejs-dataproc#620)) ([484a023](googleapis/nodejs-dataproc@484a023)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

fix: use google-gax v3.3.0 Source-Link: googleapis/synthtool@c73d112 Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-nodejs:latest@sha256:b15a6f06cc06dcffa11e1bebdf1a74b6775a134aac24a0f86f51ddf728eb373e

🤖 I have created a release *beep* *boop* --- ## [3.0.2](googleapis/nodejs-monitoring@v3.0.1...v3.0.2) (2022-09-09) ### Bug Fixes * Do not import the whole google-gax from proto JS ([#1553](https://github.com/googleapis/nodejs-monitoring/issues/1553)) ([#627](googleapis/nodejs-monitoring#627)) ([647e8ab](googleapis/nodejs-monitoring@647e8ab)) * use google-gax v3.3.0 ([647e8ab](googleapis/nodejs-monitoring@647e8ab)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

* feat: Add SavedQuery CURD support feat: Add tags support feat!：*Add RelatedAsset and deprecate RelatedAssets for relationship GA *The previous representation of the relationship feature is deprecated and unimplemented. The RelatedAsset message represents the new stable format. PiperOrigin-RevId: 449306805 Source-Link: googleapis/googleapis@3d7bd9d Source-Link: googleapis/googleapis-gen@71a93d0 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNzFhOTNkMDVkNjA3NjI3MWQwNGI3NTkyZjdmYWQwZDNmMGM3YTA0MCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com>

googlebot added the cla: yes This human has signed the Contributor License Agreement. label May 25, 2015

ryanseys reviewed May 25, 2015
View reviewed changes

lib/datastore/request.js

* numDonutsServed: 45, // detect number type (int or double)

* founded: new Date('Tue May 12 2015 15:30:00 GMT-0400 (EDT)'), // dates

* // founded: new Date('Tue May 12 2015 15:30:00 GMT-0400 (EDT)'), // dates

This comment was marked as spam.

Sign in to view

stephenplusplus mentioned this pull request May 26, 2015

docs: use a better example of how to rollback #622

Closed

stephenplusplus reviewed May 26, 2015
View reviewed changes

ryanseys added the don't merge label May 26, 2015

ryanseys mentioned this pull request May 26, 2015

Transaction Documentation #623

Closed

ryanseys reviewed May 26, 2015
View reviewed changes

ryanseys removed the don't merge label May 27, 2015

add doc examples to test suite

13bb1b8

stephenplusplus reviewed May 27, 2015
View reviewed changes

test/common/docs.js

});

it('should run docs examples without errors', function() {

for (var f in FILES) {

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

ryanseys reviewed May 27, 2015
View reviewed changes

test/common/docs.js

].join('\n'));

}

var sandbox = {

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

examples in each file now tested in own sandbox

f11cf79

stephenplusplus reviewed May 29, 2015
View reviewed changes

stephenplusplus pushed a commit that referenced this pull request May 29, 2015

Merge pull request #627 from ryanseys/verify-docs

5aff671

Verify @example docs on npm test

stephenplusplus merged commit 5aff671 into googleapis:master May 29, 2015

ryanseys deleted the verify-docs branch May 29, 2015 19:17

dhermes mentioned this pull request Jul 10, 2015

Get doctests in shape to be tested by tox googleapis/google-cloud-python#212

Closed

sofisl mentioned this pull request Nov 10, 2022

migrate code from googleapis/nodejs-text-to-speech #3528

Merged

4 tasks

release-please bot mentioned this pull request Nov 10, 2022

chore: release main #3529

Merged

sofisl pushed a commit that referenced this pull request Nov 11, 2022

fix(deps): roll back dependency @google-cloud/dataproc to ^4.0.0 (#627)

0387b16

This was referenced Nov 11, 2022

migrate code from googleapis/nodejs-dataproc #3533

Merged

migrate code from googleapis/nodejs-monitoring #3545

Merged

sofisl mentioned this pull request Nov 11, 2022

migrate code from googleapis/nodejs-asset #3567

Merged

4 tasks

sofisl added a commit that referenced this pull request Jan 24, 2023

chore: add dev deps for cloud rad (#627)

106bf2e

Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com>

sofisl added a commit that referenced this pull request Jan 25, 2023

chore: add dev deps for cloud rad (#627)

3cea433

Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com>

takeratta mentioned this pull request Jul 6, 2023

[Snyk] Security upgrade @google-cloud/logging from 1.2.0 to 6.0.0 takeratta/google-cloud-node#4

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Verify @example docs on npm test #627

Verify @example docs on npm test #627

ryanseys commented May 25, 2015

This comment was marked as spam.

jgeewax commented May 26, 2015

stephenplusplus commented May 26, 2015

This comment was marked as spam.

This comment was marked as spam.

ryanseys commented May 26, 2015

ryanseys commented May 26, 2015

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

stephenplusplus commented May 26, 2015

ryanseys commented May 27, 2015

This comment was marked as spam.

This comment was marked as spam.

stephenplusplus commented May 27, 2015

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

stephenplusplus commented May 29, 2015

ryanseys commented May 29, 2015

Verify @example docs on npm test #627

Verify @example docs on npm test #627

Conversation

ryanseys commented May 25, 2015

This comment was marked as spam.

jgeewax commented May 26, 2015

stephenplusplus commented May 26, 2015

This comment was marked as spam.

This comment was marked as spam.

ryanseys commented May 26, 2015

ryanseys commented May 26, 2015

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

stephenplusplus commented May 26, 2015

ryanseys commented May 27, 2015

This comment was marked as spam.

This comment was marked as spam.

stephenplusplus commented May 27, 2015

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

stephenplusplus commented May 29, 2015

ryanseys commented May 29, 2015