Add documentation snippet tests

peterjwest · Aug 14, 2020 · 2e481cf · 2e481cf
1 parent a9fc3a7
commit 2e481cf
Show file tree

Hide file tree

Showing 7 changed files with 129 additions and 8 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -88,6 +88,9 @@ commands:
       - run:
           name: TS Unit tests
           command: yarn test:coverage
+      - run:
+          name: Test documentation snippets
+          command: yarn test:snippets
       - store_artifacts:
           path: coverage
       - store_test_results:

diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,6 @@
 /build/es6
 /.nyc_output
 /coverage
+/tests/snippets/*
+!/tests/snippets/config.json
+!/tests/snippets/tsconfig.json
diff --git a/README.md b/README.md
@@ -16,18 +16,19 @@ yarn add sinon-mocha-test
 
 ## Usage
 
+<!-- snippet: ts,es6 -->
 ```js
 import fs from 'fs';
 import assert from 'assert';
 import sinonTest from 'sinon-mocha-test';
 
-// Example function to test
+/** Example function to test */
 async function readJsonFile(path) {
   return JSON.parse((await fs.promises.readFile(path)).toString());
 }
 
 describe('readJsonFile', () => {
-  it('Resolves with the data from a JSON file', sinonTest(async function(sinon) {
+  it('Resolves with the data from a JSON file', sinonTest(async (sinon) => {
     const readFile = sinon.stub(fs.promises, 'readFile').resolves('{"version":"123"}\n');
     assert.deepStrictEqual(await readJsonFile('file.json'), { version: '123' });
     assert.strictEqual(readFile.callCount, 1);
@@ -39,25 +40,27 @@ describe('readJsonFile', () => {
 
 Use `sinonTest.create` to specify custom Sinon sandbox options:
 
+<!-- snippet: ts,es6 -->
 ```js
 import sinonTest from 'sinon-mocha-test';
 
-// Example function to test
+/** Example function to test */
 async function delay(time) {
   return new Promise((resolve) => {
     setTimeout(resolve, time);
-  })
+  });
 }
 
 describe('delay', () => {
-  it('Resolves after a delay', sinonTest.create({ useFakeTimers: false }, async function(sinon) {
+  it('Resolves after a delay', sinonTest.create({ useFakeTimers: false }, async (sinon) => {
     await delay(10);
   }));
 });
 ```
 
 ### With CommonJS / require()
 
+<!-- snippet: js -->
 ```js
 const assert = require('assert');
 const sinonTest = require('sinon-mocha-test');

diff --git a/package.json b/package.json
@@ -42,10 +42,12 @@
     "test:coverage": "rm -rf coverage && NODE_DEBUG=nyc nyc mocha 'tests/**/*.ts'",
     "test:unit": "mocha --require ts-node/register 'tests/**/*.ts'",
     "test:unit:es5": "mocha 'tests/*.cjs'",
-    "test:unit:es6": "mocha 'tests/*.mjs'"
+    "test:unit:es6": "mocha 'tests/*.mjs'",
+    "test:snippets": "test-snippets"
   },
   "dependencies": {
-    "sinon": "^9.0.2"
+    "sinon": "^9.0.2",
+    "test-snippets": "^0.1.0"
   },
   "devDependencies": {
     "@types/bluebird": "^3.5.32",

diff --git a/tests/snippets/config.json b/tests/snippets/config.json
@@ -0,0 +1,5 @@
+{
+  "es6": { "extension": "mjs", "command": ["mocha"] },
+  "js": { "extension": "cjs", "command": ["mocha"] },
+  "ts": { "extension": "ts", "command": ["mocha", "--require", "ts-node/register"] }
+}
diff --git a/tests/snippets/tsconfig.json b/tests/snippets/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "lib": ["es2018"],
+    "module": "commonjs",
+    "baseUrl": ".",
+    "declaration": true,
+    "experimentalDecorators": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  }
+}
diff --git a/yarn.lock b/yarn.lock
@@ -260,6 +260,11 @@
   resolved "https://registry.yarnpkg.com/@types/sinonjs__fake-timers/-/sinonjs__fake-timers-6.0.1.tgz#681df970358c82836b42f989188d133e218c458e"
   integrity sha512-yYezQwGWty8ziyYLdZjwxyMb0CZR49h8JALHGrxjQHWlqGgc8kLdHEgWrgL0uZ29DMvEVBDnHU2Wg36zKSIUtA==
 
+JSV@^4.0.x:
+  version "4.0.2"
+  resolved "https://registry.yarnpkg.com/JSV/-/JSV-4.0.2.tgz#d077f6825571f82132f9dffaed587b4029feff57"
+  integrity sha1-0Hf2glVx+CEy+d/67Vh7QCn+/1c=
+
 aggregate-error@^3.0.0:
   version "3.0.1"
   resolved "https://registry.yarnpkg.com/aggregate-error/-/aggregate-error-3.0.1.tgz#db2fe7246e536f40d9b5442a39e117d7dd6a24e0"
@@ -295,14 +300,19 @@ ansi-styles@^3.2.0, ansi-styles@^3.2.1:
   dependencies:
     color-convert "^1.9.0"
 
-ansi-styles@^4.0.0:
+ansi-styles@^4.0.0, ansi-styles@^4.1.0:
   version "4.2.1"
   resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-4.2.1.tgz#90ae75c424d008d2624c5bf29ead3177ebfcf359"
   integrity sha512-9VGjrMsG1vePxcSweQsN20KY/c4zN0h9fLjqAbwbPfahM3t+NL+M9HC8xeXG2I8pX5NoamTGNuomEUFI7fcUjA==
   dependencies:
     "@types/color-name" "^1.1.1"
     color-convert "^2.0.1"
 
+ansi-styles@~1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-1.0.0.tgz#cb102df1c56f5123eab8b67cd7b98027a0279178"
+  integrity sha1-yxAt8cVvUSPquLZ817mAJ6AnkXg=
+
 anymatch@~3.1.1:
   version "3.1.1"
   resolved "https://registry.yarnpkg.com/anymatch/-/anymatch-3.1.1.tgz#c55ecf02185e2469259399310c173ce31233b142"
@@ -414,6 +424,23 @@ chalk@^2.0.0, chalk@^2.3.0, chalk@^2.4.2:
     escape-string-regexp "^1.0.5"
     supports-color "^5.3.0"
 
+chalk@^4.1.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.0.tgz#4e14870a618d9e2edd97dd8345fd9d9dc315646a"
+  integrity sha512-qwx12AxXe2Q5xQ43Ac//I6v5aXTipYrSESdOgzrN+9XjgEpyjpKuvSGaN4qE93f7TQTlerQQ8S+EQ0EyDoVL1A==
+  dependencies:
+    ansi-styles "^4.1.0"
+    supports-color "^7.1.0"
+
+chalk@~0.4.0:
+  version "0.4.0"
+  resolved "https://registry.yarnpkg.com/chalk/-/chalk-0.4.0.tgz#5199a3ddcd0c1efe23bc08c1b027b06176e0c64f"
+  integrity sha1-UZmj3c0MHv4jvAjBsCewYXbgxk8=
+  dependencies:
+    ansi-styles "~1.0.0"
+    has-color "~0.1.0"
+    strip-ansi "~0.1.0"
+
 chokidar@3.3.0:
   version "3.3.0"
   resolved "https://registry.yarnpkg.com/chokidar/-/chokidar-3.3.0.tgz#12c0714668c55800f659e262d4962a97faf554a6"
@@ -808,6 +835,11 @@ growl@1.10.5:
   resolved "https://registry.yarnpkg.com/growl/-/growl-1.10.5.tgz#f2735dc2283674fa67478b10181059355c369e5e"
   integrity sha512-qBr4OuELkhPenW6goKVXiv47US3clb3/IbuWF9KNKEijAy9oeHxU9IgzjvJhHkUzhaj7rOUD7+YGWqUjLp5oSA==
 
+has-color@~0.1.0:
+  version "0.1.7"
+  resolved "https://registry.yarnpkg.com/has-color/-/has-color-0.1.7.tgz#67144a5260c34fc3cca677d041daf52fe7b78b2f"
+  integrity sha1-ZxRKUmDDT8PMpnfQQdr1L+e3iy8=
+
 has-flag@^3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-3.0.0.tgz#b5d454dc2199ae225699f3467e5a07f3b955bafd"
@@ -1058,6 +1090,14 @@ json5@^2.1.2:
   dependencies:
     minimist "^1.2.5"
 
+jsonlint@^1.6.3:
+  version "1.6.3"
+  resolved "https://registry.yarnpkg.com/jsonlint/-/jsonlint-1.6.3.tgz#cb5e31efc0b78291d0d862fbef05900adf212988"
+  integrity sha512-jMVTMzP+7gU/IyC6hvKyWpUU8tmTkK5b3BPNuMI9U8Sit+YAWLlZwB6Y6YrdCxfg2kNz05p3XY3Bmm4m26Nv3A==
+  dependencies:
+    JSV "^4.0.x"
+    nomnom "^1.5.x"
+
 just-extend@^4.0.2:
   version "4.1.0"
   resolved "https://registry.yarnpkg.com/just-extend/-/just-extend-4.1.0.tgz#7278a4027d889601640ee0ce0e5a00b992467da4"
@@ -1129,6 +1169,11 @@ make-error@^1.1.1:
   resolved "https://registry.yarnpkg.com/make-error/-/make-error-1.3.6.tgz#2eb2e37ea9b67c4891f684a1394799af484cf7a2"
   integrity sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==
 
+marked@^1.1.0:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/marked/-/marked-1.1.1.tgz#e5d61b69842210d5df57b05856e0c91572703e6a"
+  integrity sha512-mJzT8D2yPxoPh7h0UXkB+dBj4FykPJ2OIfxAWeIHrvoHDkFxukV/29QxoFQoPM6RLEwhIFdJpmKBlqVM3s2ZIw==
+
 minimatch@3.0.4, minimatch@^3.0.4:
   version "3.0.4"
   resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.0.4.tgz#5166e286457f03306064be5497e8dbb0c3d32083"
@@ -1148,6 +1193,11 @@ mkdirp@0.5.5, mkdirp@^0.5.3:
   dependencies:
     minimist "^1.2.5"
 
+mkdirp@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-1.0.4.tgz#3eb5ed62622756d79a5f0e2a221dfebad75c2f7e"
+  integrity sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==
+
 mocha@^7.2.0:
   version "7.2.0"
   resolved "https://registry.yarnpkg.com/mocha/-/mocha-7.2.0.tgz#01cc227b00d875ab1eed03a75106689cfed5a604"
@@ -1196,6 +1246,11 @@ ms@^2.1.1:
   resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.2.tgz#d09d1f357b443f493382a8eb3ccd183872ae6009"
   integrity sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==
 
+multiline-ts@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/multiline-ts/-/multiline-ts-2.0.0.tgz#7d93ebf0290c32c7a93f7bc4c19af5d52a6c9012"
+  integrity sha512-esdWnghYoW+2aR9hs26NWHvDfo76DmhfS6hJAjwz+RpzFWouv6KUhup5ro2kDijclQWobDYaYnJAdVUE69kKSw==
+
 nise@^4.0.4:
   version "4.0.4"
   resolved "https://registry.yarnpkg.com/nise/-/nise-4.0.4.tgz#d73dea3e5731e6561992b8f570be9e363c4512dd"
@@ -1229,6 +1284,14 @@ node-version-matches@^1.0.1:
   dependencies:
     semver "^5.6.0"
 
+nomnom@^1.5.x:
+  version "1.8.1"
+  resolved "https://registry.yarnpkg.com/nomnom/-/nomnom-1.8.1.tgz#2151f722472ba79e50a76fc125bb8c8f2e4dc2a7"
+  integrity sha1-IVH3Ikcrp55Qp2/BJbuMjy5Nwqc=
+  dependencies:
+    chalk "~0.4.0"
+    underscore "~1.6.0"
+
 normalize-path@^2.1.1:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/normalize-path/-/normalize-path-2.1.1.tgz#1ab28b556e198363a8c1a6f7e6fa20137fe6aed9"
@@ -1560,6 +1623,11 @@ source-map@^0.6.0, source-map@^0.6.1:
   resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263"
   integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==
 
+spawn-process@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/spawn-process/-/spawn-process-1.0.4.tgz#7a7648a52574aded8c00d9ae4e80b724ec925b34"
+  integrity sha512-7TWp8zl/i999jMlkb0bYH4061JxWSSUo27l0A7UHa0J3HwkVHNbRsVk8yOEf6Hh1PDRh9plftRsBd1IohhOmvQ==
+
 spawn-wrap@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/spawn-wrap/-/spawn-wrap-2.0.0.tgz#103685b8b8f9b79771318827aa78650a610d457e"
@@ -1645,6 +1713,11 @@ strip-ansi@^6.0.0:
   dependencies:
     ansi-regex "^5.0.0"
 
+strip-ansi@~0.1.0:
+  version "0.1.1"
+  resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-0.1.1.tgz#39e8a98d044d150660abe4a6808acf70bb7bc991"
+  integrity sha1-OeipjQRNFQZgq+SmgIrPcLt7yZE=
+
 strip-bom@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-4.0.0.tgz#9c3505c1db45bcedca3d9cf7a16f5c5aa3901878"
@@ -1695,6 +1768,21 @@ test-exclude@^6.0.0:
     glob "^7.1.4"
     minimatch "^3.0.4"
 
+test-snippets@^0.1.0:
+  version "0.1.0"
+  resolved "https://registry.yarnpkg.com/test-snippets/-/test-snippets-0.1.0.tgz#f8f99ae7c7e6d7b9a2d91090eb9d88fe1a0c66f7"
+  integrity sha512-+We2oGencVEMbBrdfIMGpn0DLOBEdbrAJzDD8/AE4SwG3ii1GOI8zBhQkv5IluFI/RrcCOMeVNemV7Tlfbd4dA==
+  dependencies:
+    bluebird "^3.7.2"
+    chalk "^4.1.0"
+    glob "^7.1.6"
+    jsonlint "^1.6.3"
+    lodash "^4.17.15"
+    marked "^1.1.0"
+    mkdirp "^1.0.4"
+    multiline-ts "^2.0.0"
+    spawn-process "^1.0.4"
+
 to-fast-properties@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/to-fast-properties/-/to-fast-properties-2.0.0.tgz#dc5e698cbd079265bc73e0377681a4e4e83f616e"
@@ -1811,6 +1899,11 @@ typical@^5.0.0, typical@^5.2.0:
   resolved "https://registry.yarnpkg.com/typical/-/typical-5.2.0.tgz#4daaac4f2b5315460804f0acf6cb69c52bb93066"
   integrity sha512-dvdQgNDNJo+8B2uBQoqdb11eUCE1JQXhvjC/CZtgvZseVd5TYMXnq0+vuUemXbd/Se29cTaUuPX3YIc2xgbvIg==
 
+underscore@~1.6.0:
+  version "1.6.0"
+  resolved "https://registry.yarnpkg.com/underscore/-/underscore-1.6.0.tgz#8b38b10cacdef63337b8b24e4ff86d45aea529a8"
+  integrity sha1-izixDKze9jM3uLJOT/htRa6lKag=
+
 uuid@^3.3.3:
   version "3.4.0"
   resolved "https://registry.yarnpkg.com/uuid/-/uuid-3.4.0.tgz#b23e4358afa8a202fe7a100af1f5f883f02007ee"