feat: add export Markdown to JavaScript bin (#93)

* feat: add export Markdown to JavaScript bin

* show the exported JS file

Author: bahmutov

.github/workflows/ci.yml

@@ -19,6 +19,12 @@ jobs:
         with:
           command: npm t
 
+      - name: Test exporting Markdown to JavaScript 🖨
+        run: |
+          node ./bin/export-fiddles cypress/integration/skip.md
+          cat cypress/integration/skip.js
+          # TODO: confirm the exported JavaScript file
+
       - name: Semantic Release 🚀
         uses: cycjimmy/semantic-release-action@v2
         with:

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 cypress/videos
 cypress/screenshots
+cypress/integration/*.js

README.md

@@ -83,6 +83,17 @@ You can skip JS blocks in the fiddle by using `js skip` syntax
     ```
 ````
 
+## Exporting JS specs from Markdown fiddles
+
+```shell
+# saves path/to/md.js file
+npx export-fiddle <path/to/md>
+# adds optional "beforeEach" hook with cy.visit(url)
+npx export-fiddle <path/to/md> --before-each <url>
+# adds optional "before" hook with cy.visit(url)
+npx export-fiddle <path/to/md> --before <url>
+```
+
 ## Examples
 
 See the presentation [Using End-to-end Tests as Documentation](https://slides.com/bahmutov/tests-are-docs)

bin/export-fiddles.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// @ts-check
+
+const debug = require('debug')('cypress-markdown-preprocessor')
+const path = require('path')
+const fs = require('fs')
+const arg = require('arg')
+const mdUtils = require('../src/markdown-utils')
+const writeUtils = require('../src/write-utils')
+
+const args = arg({
+  '--before': String, // visit an URL
+  '--before-each': String, // visit an URL before each test
+})
+
+const markdownFilename = args._[0]
+if (!markdownFilename || path.extname(markdownFilename) !== '.md') {
+  throw new Error(
+    `Expected markdown filename, got ${markdownFilename}`,
+  )
+}
+
+const outputFilename = markdownFilename.replace(/\.md$/, '.js')
+const md = fs.readFileSync(markdownFilename, 'utf8')
+const tests = mdUtils.extractFiddles(md)
+debug('found tests %o', tests)
+const source = writeUtils.generateSpec(tests, {
+  before: args['--before'],
+  beforeEach: args['--before-each'],
+  beforeHooksAtDepth: 1, // only add the hooks to 1 level deep
+})
+fs.writeFileSync(outputFilename, source + '\n', 'utf8')
+console.log('saved %s', outputFilename)

cypress/integration/skip.md

@@ -0,0 +1,12 @@
+<!-- fiddle With skip bloc -->
+
+```js
+console.log('here')
+```
+
+```js skip
+// should not be exported
+console.log('nope')
+```
+
+<!-- fiddle-end -->

package.json

@@ -4,8 +4,12 @@
   "description": "Use Markdown files as Cypress specs",
   "main": "src/index.js",
   "files": [
-    "src"
+    "src",
+    "bin"
   ],
+  "bin": {
+    "export-fiddles": "bin/export-fiddles.js"
+  },
   "scripts": {
     "cy:open": "cypress open",
     "cy:run": "cypress run",

src/write-utils.js

@@ -0,0 +1,119 @@
+// @ts-check
+const { source } = require('common-tags')
+const debug = require('debug')('cypress-markdown-preprocessor')
+
+const isTestObject = (o) => o.test
+
+function generateTest(name, maybeTest) {
+  if (typeof name !== 'string') {
+    console.error(maybeTest)
+    throw new Error('Test has no name ' + name)
+  }
+
+  let itName = 'it'
+  if (maybeTest.skip) {
+    itName = 'it.skip'
+  } else if (maybeTest.only) {
+    itName = 'it.only'
+  }
+
+  return source`
+    ${itName}('${name}', () => {
+      ${maybeTest.test}
+    })
+  `
+}
+
+/**
+ * Processes a tree of test definitions, each with HTML and JS
+ * and returns generated spec file source
+ */
+function generateSpecWorker(maybeTest, options) {
+  let start = ''
+
+  if (options.beforeHooksAtDepth === options.depth) {
+    if (options.before) {
+      start =
+        source`
+        before(() => {
+          cy.visit('${options.before}')
+        })
+      ` + '\n\n'
+    } else if (options.beforeEach) {
+      start =
+        source`
+        beforeEach(() => {
+          cy.visit('${options.before}')
+        })
+      ` + '\n\n'
+    }
+  }
+
+  if (isTestObject(maybeTest)) {
+    debug('single test object')
+    return start + generateTest(maybeTest.name, maybeTest)
+  }
+
+  if (Array.isArray(maybeTest)) {
+    // console.log('list of tests')
+    const sources = maybeTest.map((test) => {
+      if (isTestObject(test)) {
+        return generateTest(test.name, test)
+      } else {
+        const nextCallOptions = {
+          ...options,
+          depth: options.depth + 1,
+        }
+        return generateSpecWorker(test, nextCallOptions)
+      }
+    })
+    return start + sources.join('\n\n')
+  }
+
+  const sources = Object.keys(maybeTest).map((name) => {
+    debug('generating test for name "%s"', name)
+    const value = maybeTest[name]
+    // console.log({ name, value })
+
+    if (isTestObject(value)) {
+      // console.log('%s is a test', name)
+
+      if (value.skip && value.only) {
+        throw new Error(`Test ${name} has both skip and only true`)
+      }
+
+      return generateTest(name, value)
+    }
+
+    const nextCallOptions = {
+      ...options,
+      depth: options.depth + 1,
+    }
+
+    // final choice - create nested suite of tests
+    const inner = generateSpecWorker(value, nextCallOptions)
+    return source`
+      describe('${name}', () => {
+        ${inner}
+      })
+    `
+  })
+
+  return start + sources.join('\n')
+}
+
+function generateSpec(maybeTest, options = {}) {
+  const opts = {
+    ...options,
+    depth: 0,
+  }
+
+  const specSource = generateSpecWorker(maybeTest, opts)
+  const preamble =
+    source`
+    /// <reference types="cypress" />
+  ` + '\n'
+  return preamble + specSource
+}
+
+module.exports = { generateSpec }