Improve organization of, and add comments to, CLI and functional tests.

Author: DPassarelli

.appveyor.yml

@@ -28,7 +28,7 @@ before_test:
 test_script:
   - npm run lint
   - npx mocha --reporter mocha-junit-reporter --reporter-options mochaFile=./tr-unit.xml index.spec.js
-  - npx mocha --reporter mocha-junit-reporter --reporter-options mochaFile=./tr-func.xml test/functional/*
+  - npx mocha --reporter mocha-junit-reporter --reporter-options mochaFile=./tr-func.xml test/functional/*.spec.js
 
 after_test:
   - ps: |

bin/cli.js

@@ -3,13 +3,14 @@
 const path = require('path')
 const fs = require('fs').promises
 const log = console.log
-const validate = require('../index.js')
+const validateFn = require('../index.js')
 
 /**
- * [validateStdIn description]
+ * Returns the data piped into this process on stdin.
+ *
  * @return {Promise}
  */
-function validateStdIn () {
+function captureInputFromStdIn () {
   log('Validating XML from stdin...')
 
   return new Promise((resolve, reject) => {
@@ -29,53 +30,52 @@ function validateStdIn () {
     })
 
     process.stdin.on('end', () => {
-      validate(input.join(''))
-        .then(resolve)
+      resolve(input.join(''))
     })
   })
 }
 
 /**
- * [validateFile description]
- * @param  {[type]} resolvedPath [description]
+ * Returns the contents of the specified file.
+ *
+ * @param  {String}   p   The path to the file.
+ *
  * @return {Promise}
  */
-function validateFile (resolvedPath) {
-  log('Validating XML from path "%s"...', resolvedPath)
+function captureInputFromFile (p) {
+  const resolvedPath = path.resolve(p)
 
+  log('Validating the file at "%s"...', resolvedPath)
   return fs.readFile(resolvedPath)
-    .then((contents) => {
-      return validate(contents)
-    })
 }
 
 /**
- * [displayResult description]
- * @param  {[type]} result [description]
+ * Outputs the results of the XML validation to the log.
+ *
  * @return {undefined}
  */
-function logStatusOfValidation (status) {
+function logResultOfXmlValidation (dtd, warnings, errors) {
   log('')
 
-  if (status.errors.length === 0) {
-    log('Congratulations, the provided XML is well-formed and valid, according to the DTD at "%s"', status.dtd)
+  if (errors.length === 0) {
+    log('Congratulations, the provided XML is well-formed and valid, according to the DTD at "%s"', dtd)
 
-    if (status.warnings.length > 0) {
+    if (warnings.length > 0) {
       log('')
       log('However, please note the following warnings:')
-      status.warnings.forEach((msg) => { log('  -', msg) })
+      warnings.forEach((msg) => { log('  -', msg) })
     }
   } else {
-    log('Unfortunately, the provided XML does not validate according to the DTD at "%s"', status.dtd)
+    log('Unfortunately, the provided XML does not validate according to the DTD at "%s"', dtd)
     log('')
     log('The following errors were reported:')
 
-    status.errors.forEach((msg) => { log('  ✘', msg) })
+    errors.forEach((msg) => { log('  ✘', msg) })
 
-    if (status.warnings.length > 0) {
+    if (warnings.length > 0) {
       log('')
       log('Also, please note the following warnings:')
-      status.warnings.forEach((msg) => { log('  -', msg) })
+      warnings.forEach((msg) => { log('  -', msg) })
     }
   }
 }
@@ -85,22 +85,23 @@ function logStatusOfValidation (status) {
  * @return {undefined}
  */
 async function main () {
-  let validationResult = null
+  let xml = ''
   const args = process.argv.slice(2)
 
   try {
     if (args.length === 0) {
-      validationResult = await validateStdIn()
+      xml = await captureInputFromStdIn()
     } else {
-      const resolvedPath = path.resolve(args[0])
-      validationResult = await validateFile(resolvedPath)
+      xml = await captureInputFromFile(args[0])
     }
 
-    logStatusOfValidation({
-      dtd: validationResult.doctype,
-      errors: validationResult.errors,
-      warnings: validationResult.warnings
-    })
+    const validationResult = await validateFn(xml)
+
+    logResultOfXmlValidation(
+      validationResult.doctype,
+      validationResult.warnings,
+      validationResult.errors
+    )
 
     if (validationResult.errors.length > 0) {
       process.exit(1)

package.json

@@ -8,7 +8,7 @@
   },
   "scripts": {
     "test:unit": "mocha index.spec.js",
-    "test:func": "mocha test/functional/*",
+    "test:func": "mocha test/functional/*.spec.js",
     "test": "npm run lint && npm run check-coverage && npm run test:func",
     "lint": "standard",
     "check-coverage": "nyc npm run test:unit",

test/functional/cli-runner.js

@@ -0,0 +1,45 @@
+const childProcess = require('child_process')
+
+/**
+ * Spawns a child process to run the given CLI command. The return code, and
+ * outputs of `stdout` and `stderr`, are captured for later analysis.
+ *
+ * @param  {String}   cmd   The command to run, which will be executed in a
+ *                          shell context.
+ *
+ * @return {Promise}        Resolving to an object with properties `code`,
+ *                          `stdin` and `stderr`.
+ */
+function exported (cmd) {
+  return new Promise((resolve, reject) => {
+    const output = {
+      stdout: [],
+      stderr: []
+    }
+
+    const proc = childProcess.spawn(cmd, { cwd: process.cwd(), shell: true })
+
+    proc.stdout.on('data', (data) => {
+      const stringValue = data.toString()
+      console.log(stringValue) // this is to indicate actual progress as the tests are running
+      output.stdout.push(stringValue)
+    })
+
+    proc.stderr.on('data', (data) => {
+      const stringValue = data.toString()
+      console.error(stringValue) // (same)
+      output.stderr.push(stringValue)
+    })
+
+    proc.on('error', (err) => {
+      reject(err)
+    })
+
+    proc.on('exit', (code, signal) => {
+      output.code = code
+      resolve(output)
+    })
+  })
+}
+
+module.exports = exported

test/functional/submission-to-w3c.js test/functional/submission-to-w3c.spec.js

@@ -7,10 +7,10 @@ const path = require('path')
  * Code under test.
  * @type {any}
  */
-const T = require(path.join(__dirname, '../../index.js'))
+const T = require(path.resolve('./index.js'))
 
-const VALID_XML = fs.readFileSync(path.join(__dirname, '../samples/valid.xml'))
-const INVALID_XML = fs.readFileSync(path.join(__dirname, '../samples/invalid.xml'))
+const VALID_XML = fs.readFileSync(path.resolve('./test/samples/valid.xml'))
+const INVALID_XML = fs.readFileSync(path.resolve('./test/samples/invalid.xml'))
 
 describe('an actual submission to W3C', function () {
   context('with a valid document', function () {

test/functional/test-cli.js test/functional/test-cli.spec.js

@@ -1,65 +1,24 @@
 /* eslint-env mocha */
 
-const childProcess = require('child_process')
 const path = require('path')
+const cliRunner = require('./cli-runner.js')
 
 /**
- * [isWindowsPlatform description]
+ * A flag indicating whether the current OS is based on MS Windows.
  * @type {Boolean}
  */
-const isWindowsPlatform = (require('os').platform() === 'win32')
+const isWindowsOS = require('os').platform().startsWith('win')
 
 /**
- * [command description]
+ * The appropriate way to call the CLI, depending on the detected OS type.
  * @type {String}
  */
-const callee = (
-  isWindowsPlatform
+const cli = (
+  isWindowsOS
     ? 'node .\\bin\\cli.js'
     : './bin/cli.js'
 )
 
-/**
- * Spawns a child process to run the CLI command given. The return code, and
- * output of `stdout` and `stderr` are captured for later analysis by the tests.
- *
- * @param  {String}   cmd   The command to run, which will be executed in a
- *                          shell context.
- *
- * @return {Promise}
- */
-function runChildProcess (cmd) {
-  return new Promise((resolve, reject) => {
-    const output = {
-      stdout: [],
-      stderr: []
-    }
-
-    const proc = childProcess.spawn(
-      cmd,
-      {
-        cwd: process.cwd(),
-        shell: true
-      }
-    )
-
-    proc.stdout.on('data', (data) => {
-      console.log(data.toString()) // this is to indicate actual progress as the tests are running
-      output.stdout.push(data)
-    })
-
-    proc.stderr.on('data', (data) => {
-      console.error(data.toString()) // (same)
-      output.stderr.push(data)
-    })
-
-    proc.on('exit', (code, signal) => {
-      output.code = code
-      resolve(output)
-    })
-  })
-}
-
 const pathToValidSampleXmlFile = path.resolve('./test/samples/valid.xml')
 const pathToInvalidSampleXmlFile = path.resolve('./test/samples/invalid.xml')
 
@@ -71,12 +30,12 @@ describe('the command-line interface', function () {
       this.timeout(8000) // sometimes the request to W3C takes a bit longer than the default timeout of 2 sec
 
       const cmd = (
-        isWindowsPlatform
-          ? `type ${pathToValidSampleXmlFile} | ${callee}`
-          : `cat ${pathToValidSampleXmlFile} | ${callee}`
+        isWindowsOS
+          ? `type ${pathToValidSampleXmlFile} | ${cli}`
+          : `cat ${pathToValidSampleXmlFile} | ${cli}`
       )
 
-      return runChildProcess(cmd)
+      return cliRunner(cmd)
         .then(function (output) {
           result = output
         })
@@ -109,7 +68,7 @@ However, please note the following warnings:
     before(function () {
       this.timeout(8000)
 
-      return runChildProcess(`${callee} ${pathToInvalidSampleXmlFile}`)
+      return cliRunner(`${cli} ${pathToInvalidSampleXmlFile}`)
         .then(function (output) {
           result = output
         })
@@ -123,7 +82,7 @@ However, please note the following warnings:
     })
 
     it('must output the expected text', function () {
-      const expected = `Validating XML from path "${pathToInvalidSampleXmlFile}"...
+      const expected = `Validating the file at "${pathToInvalidSampleXmlFile}"...
 
 Unfortunately, the provided XML does not validate according to the DTD at "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd"