@small-tech/tap-monkey 1.1.1 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2022-05-24
+
+Testy monkey.
+
+## Added
+
+  - 100% code coverage. Now using tape and *drumroll* Tap Monkey itself for the tests.
+
+## [1.3.0] - 2021-03-05
+
+Debug monkey.
+
+## Added
+
+  - Now displays console output from your app if there is any (useful for debugging).
+
+## [1.2.0] - 2021-03-04
+
+Bail-out monkey.
+
+## Added
+
+  - Handles bail-out events.
+
+## Updated
+
+  - tap-out: version 3.1.0 → 3.2.0
+
 ## [1.1.1] - 2021-03-03
 
 Fix typos.

package/README.md

@@ -64,7 +64,7 @@ e.g., using [c8](https://github.com/bcoe/c8):
 
 ```json
 "scripts" : {
-  "test": "c8 tape test/**/*js | tap-monkey"
+  "coverage": "c8 tape test/**/*js | tap-monkey"
 }
 ```
 
@@ -76,6 +76,53 @@ While passing tests are displayed ephemerally in the status line so as not to fi
 
 (When running tests, we don’t care about passing tests, only failing ones.)
 
+## Debug output
+
+Any console output that is generated by your program (e.g., from `console.log()` statements) is displayed in full and separate from the current test status line.
+
+This is useful while debugging. (I like to have regular and debug test tasks in my code and use the latter when debugging an issue encountered in a test.)
+
+e.g., my regular tests define an environment variable that silences console output but I have a separate debug test task that doesn’t include this.
+
+```json
+"scripts" : {
+  "test": "QUIET=true tape test/**/*js | tap-monkey",
+  "test-debug": "tape test/**/*js | tap-monkey"
+}
+```
+
+Then, all you need is to use a conditional log function in your app that checks for that environment variable. e.g.,
+
+```js
+// Conditionally log to console.
+export default function log (...args) {
+  if (process.env.QUIET) {
+    return
+  }
+  console.log(...args)
+}
+```
+
+## Error behaviour
+
+If your test runner (e.g., [ESM Tape Runner](https://github.com/small-tech/esm-tape-runner)) encounters an error in your app’s source code (e.g., a syntax error in one of your classes), it should bail out (and hopefully also log the error so you know what it is). Tap Monkey will respond to bail out events by displaying them and exiting (your test runner should have exit also so you should not get any pipe errors).
+
+## Testing Tap Monkey
+
+Tap Monkey itself, of course, comes with unit tests displayed by none other than _\*drumroll\*_ Tap Monkey!
+
+### Run tests
+
+```shell
+npm run -s test
+```
+
+### Run coverage
+
+```shell
+npm run -s coverage
+```
+
 ## Like this? Fund us!
 
 [Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.

package/index.js

@@ -16,14 +16,15 @@ import Ora from 'ora'
 import chalk from 'chalk'
 import { performance } from 'perf_hooks'
 import tapOut from '@small-tech/tap-out'
-
-let hasFailures = false
+import os from 'os'
 
 // The formatter has a --quiet option that stops status updates being
 // printed until there is a failure or until the aggregate statistics is
 // being shown. People using screen readers and other assistive technologies
 // might want to use this if the number of status updates becomes overwhelming.
-let quiet = (process.argv.length === 3 && process.argv[2] === '--quiet')
+export const context = {
+  quiet: (process.argv.length === 3 && process.argv[2] === '--quiet')
+}
 
 // Due to the 300ms frame duration of the monkey animation, not every
 // status update we receive about new test suites and test passes will be
@@ -54,23 +55,22 @@ let printingCoverage = false
 let coverageBorderCount = 0
 let currentTest = ''
 
-parser.on('test', test => {
-  spinner.start()
-  if (!quiet) {
-    currentTest = test.name
-    spinner.text = `Running ${chalk.underline(currentTest)} tests`
+const passHandler = (assert => {
+  if (!context.quiet) {
+    spinner.text = `${chalk.green('✔')} ${assert.name}`
   }
 })
 
-parser.on('pass', assert => {
-  if (!quiet) {
-    spinner.text = `${chalk.green('✔')} ${assert.name}`
+const testHandler = (test => {
+  spinner.start()
+  if (!context.quiet) {
+    currentTest = test.name
+    spinner.text = `Running ${chalk.underline(currentTest)} tests`
   }
 })
 
-parser.on('fail', assert => {
+const failHandler = (assert => {
   // Stop the spinner and output failures in full.
-  hasFailures = true
   spinner.stop()
 
   const e = assert.error
@@ -80,50 +80,57 @@ parser.on('fail', assert => {
   if (e.operator !== undefined) console.log(`  operator:`, e.operator)
   if (e.expected !== undefined) console.log(`  ${chalk.green(`expected: ${e.expected}`)}`)
   if (e.actual !== undefined)   console.log(`  ${chalk.red(`actual  : ${e.actual}`)}`)
-  if (e.at !== undefined)       console.log(`  ${chalk.yellow(`at      : ${e.at}`)}`)
+  if (e.at !== undefined)       console.log(`  ${chalk.yellow(`at      : ${e.at.file.replace(os.homedir(), '~')}:${e.at.line}:${e.at.character}`)}`)
 
   console.log()
 
   e.stack.split('\n').forEach(line => {
-    console.log(' ', chalk.gray(line))
+    console.log(' ', chalk.red(line))
   })
 
   spinner.start()
 })
 
-parser.on('comment', comment => {
-  let commentText = comment.raw
-
-  if (commentText.startsWith('----')) {
-    // We take the first comment that includes a border to signal the
-    // start of the coverage section and stop the spinner permanently
-    // from there on.
-    if (!printingCoverage) {
-      printingCoverage = true
-      spinner.stop()
-    }
+const bailOutHandler = (event => {
+  // If the test runner has emitted a bail out event, it has signaled
+  // that it cannot continue. So we notify the person and exit.
+  spinner.stop()
+  console.error(chalk.red(event.raw))
+  console.error()
+  process.exit(1)
+})
 
-    coverageBorderCount++
-    switch(coverageBorderCount) {
-      case 1: commentText = `╭─${commentText.replace(/\-\|\-/g, '─┬─')}─╮`; break
-      case 2: commentText = `├─${commentText.replace(/\-\|\-/g, '─┼─')}─┤`; break
-      case 3: commentText = `╰─${commentText.replace(/\-\|\-/g, '─┴─')}─╯\n`; break
-      default: throw new Error('Too many borders found in coverage. Panic!')
-    }
-  } else {
-    commentText = `│ ${commentText} │`
-  }
+const commentHandler = (comment => {
+  spinner.stop()
+  let commentText = comment.raw
+  
+  const isCoverageBorder = commentText.startsWith('----')
+  if (isCoverageBorder) { printingCoverage = true }
 
   if (printingCoverage) {
+    if (isCoverageBorder) {
+      coverageBorderCount++
+      switch(coverageBorderCount) {
+        case 1: commentText = `╭─${commentText.replace(/\-\|\-/g, '─┬─')}─╮`; break
+        case 2: commentText = `├─${commentText.replace(/\-\|\-/g, '─┼─')}─┤`; break
+        case 3: commentText = `╰─${commentText.replace(/\-\|\-/g, '─┴─')}─╯\n`; break
+        default: throw new Error('Too many borders found in coverage. Panic!')
+      }
+    } else {
+      // Printing coverage but this line isn’t a border, just surround it with vertical borders.
+      commentText = `│ ${commentText} │`
+    }
+    // Replace any inner borders that there might be with proper box-drawing characters.
     console.log(commentText.replace(/\|/g, '│').replace(/\-/g, '─'))
   } else {
-    // We haven’t started printing coverage yet so this must be some other TAP comment.
-    // Display it in the status line.
-    spinner.text = commentText
+    // We aren’t printing coverage yet so this must be a regular TAP comment.
+    // Display it fully.
+    console.log(chalk.yellow('   🢂 '), commentText.trim())
+    spinner.start()
   }
 })
 
-parser.on('output', results => {
+const outputHandler = (results => {
   const duration = ((performance.now() - startTime)/1000).toFixed(2)
   spinner.stop()
 
@@ -131,7 +138,9 @@ parser.on('output', results => {
   const passing = results.pass.length
   const failing = results.fail.length
 
-  if (hasFailures) {
+  // TODO: Handle edge case of zero total tests.
+  
+  if (failing > 0) {
     console.log(`  🙊️ ${chalk.magenta('There are failed tests.')}`)
   } else {
     console.log(`  🍌️ ${chalk.green('All tests passing!')}`)
@@ -143,3 +152,13 @@ parser.on('output', results => {
   console.log(chalk.red(  `  Failing   ${failing}`))
   console.log(chalk.gray( `  Duration  ${duration} secs`))
 })
+
+parser.on('test', testHandler)
+parser.on('pass', passHandler)
+parser.on('fail', failHandler)
+parser.on('bailOut', bailOutHandler)
+parser.on('comment', commentHandler)
+parser.on('output', outputHandler)
+
+export default { testHandler, passHandler, failHandler, bailOutHandler, commentHandler, outputHandler, parser, spinner }
+

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@small-tech/tap-monkey",
-  "version": "1.1.1",
+  "version": "1.4.0",
   "description": "A tap formatter that’s also a monkey.",
-  "keywords": ["tap", "formatter", "tape", "nyc", "c8", "test anything protocol", "accessible", "a11y"],
+  "keywords": [
+    "tap",
+    "formatter",
+    "tape",
+    "nyc",
+    "c8",
+    "test anything protocol",
+    "accessible",
+    "a11y"
+  ],
   "license": "ISC",
   "main": "index.js",
   "type": "module",
@@ -10,7 +19,8 @@
     "tap-monkey": "./index.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "tape tests/index.js | node index.js",
+    "coverage": "c8 tape tests/index.js | node index.js"
   },
   "author": {
     "name": "Aral Balkan",
@@ -24,8 +34,13 @@
     "url": "https://github.com/small-tech/tap-monkey.git"
   },
   "dependencies": {
-    "@small-tech/tap-out": "^3.1.0",
+    "@small-tech/tap-out": "^3.2.0",
     "chalk": "^4.1.0",
     "ora": "^5.3.0"
+  },
+  "devDependencies": {
+    "c8": "^7.11.3",
+    "strip-ansi": "^7.0.1",
+    "tape": "^5.5.3"
   }
 }

package/tests/index.js

@@ -0,0 +1,295 @@
+import test from 'tape'
+import tapMonkey from '../index.js'
+import { context } from '../index.js'
+import strip from 'strip-ansi'
+
+// Since Tap Monkey pipes stdin, this will leave a handle open.
+// We have to destroy stdin when all tests are done for the 
+// runner to exit properly.
+// See https://github.com/nodejs/node/issues/32291
+
+test.onFinish(() => {
+  process.stdin.destroy()
+})
+
+//
+// Test handler and general tests.
+//
+
+test('test handler', t => {
+  context.quiet = false
+  tapMonkey.testHandler({name: 'mock'})
+  tapMonkey.spinner.stop()
+
+  t.strictEquals(tapMonkey.spinner._spinner.interval, 300, 'spinner interval is as expected')
+  t.strictEquals(tapMonkey.spinner._spinner.frames[0], '  🙈 ', 'animation frame 1 is correct')
+  t.strictEquals(tapMonkey.spinner._spinner.frames[1], '  🙈 ', 'animation frame 2 is correct')
+  t.strictEquals(tapMonkey.spinner._spinner.frames[2], '  🙉 ', 'animation frame 3 is correct')
+  t.strictEquals(tapMonkey.spinner._spinner.frames[3], '  🙊 ', 'animation frame 4 is correct')
+
+  t.true(strip(tapMonkey.spinner.text).includes('Running mock tests'), 'test name is displayed correctly')
+  
+  context.quiet = true
+  tapMonkey.testHandler({name: 'quiet mock'})
+  tapMonkey.spinner.stop()
+  
+  t.false(strip(tapMonkey.spinner.text).includes('Running quiet mock tests'), 'test name not displayed in quiet mode')
+    
+  t.end()
+})
+
+//
+// Pass handler tests.
+//
+
+test('pass handler', t => {
+  // Quiet passes (the default)
+  context.quiet = true
+  const quietPass = 'a quiet pass'
+  tapMonkey.passHandler({ name: quietPass })
+  t.false(tapMonkey.spinner.text.includes(quietPass), 'quiet mode should not display passed tests')
+  
+  // Loud passes.
+  context.quiet = false
+  const loudPass = 'a loud pass'
+  tapMonkey.passHandler({ name: loudPass })
+  t.true(tapMonkey.spinner.text.includes(loudPass), 'passed tests should display when quiet mode is off')
+  
+  t.end()
+})
+
+//
+// Fail handler tests.
+//
+
+test('fail handler', t => {
+  // Capture console log temporarily.
+  const originalConsoleLog = console.log
+  let output = ''
+  const capturedConsoleLog = (...args) => output += args.join(' ')
+  console.log = capturedConsoleLog
+
+  const mockAssertionWithTypeError = {
+    type: 'assert',
+    raw: 'not ok 2 TypeError: Cannot convert undefined or null to object',
+    ok: false,
+    number: 2,
+    name: 'TypeError: Cannot convert undefined or null to object',
+    error: {
+      operator: 'error',
+      expected: undefined,
+      actual: undefined,
+      at: {
+        file: '/var/home/aral/Projects/nodekit/node_modules/tape-promise/node_modules/onetime/index.js',
+        line: '30',
+        character: '12'
+      },
+      stack: 'TypeError: Cannot convert undefined or null to object\n' +
+        'at Function.keys (<anonymous>)\n' +
+        'at sortResults (file:///var/home/aral/Projects/nodekit/tests/files.js:17:10)\n' +
+        'at file:///var/home/aral/Projects/nodekit/tests/files.js:101:58\n' +
+        'at processTicksAndRejections (node:internal/process/task_queues:96:5)\n',
+      raw: '    operator: error\n' +
+        '    at: bound (/var/home/aral/Projects/nodekit/node_modules/tape-promise/node_modules/onetime/index.js:30:12)\n' +
+        '    stack: |-\n' +
+        'TypeError: Cannot convert undefined or null to object\n' +
+        'at Function.keys (<anonymous>)\n' +
+        'at sortResults (file:///var/home/aral/Projects/nodekit/tests/files.js:17:10)\n' +
+        'at file:///var/home/aral/Projects/nodekit/tests/files.js:101:58\n' +
+        'at processTicksAndRejections (node:internal/process/task_queues:96:5)'
+    },
+    test: 10
+  }
+
+  tapMonkey.failHandler(mockAssertionWithTypeError)
+  tapMonkey.spinner.stop()
+  console.log = originalConsoleLog
+
+  t.true(output.includes('TypeError: Cannot convert undefined or null to object'), 'output includes main error message')
+  t.true(output.includes('~/Projects/nodekit/node_modules/tape-promise/node_modules/onetime/index.js:30:12'), 'error location shown')
+  
+  // Test a regular assertion failure.
+  
+  output = ''
+  console.log = capturedConsoleLog
+  
+  const regularFailedAssertion = {
+    type: 'assert',
+    raw: 'not ok 8 quiet mode should not display passed tests',
+    ok: false,
+    number: 8,
+    name: 'quiet mode should not display passed tests',
+    error: {
+      operator: 'ok',
+      expected: 'true',
+      actual: 'false',
+      at: undefined,
+      stack: 'Error: quiet mode should not display passed tests\n' +
+        'at Test.assert [as _assert] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:314:54)\n' +
+        'at Test.bound [as _assert] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Test.assert (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:433:10)\n' +
+        'at Test.bound [as true] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Test.<anonymous> (file:///var/home/aral/Projects/tap-monkey/tests/index.js:50:9)\n' +
+        'at Test.bound [as _cb] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Test.run (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:117:31)\n' +
+        'at Test.bound [as run] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Immediate.next [as _onImmediate] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/results.js:88:19)\n' +
+        'at processImmediate (node:internal/timers:466:21)\n',
+      raw: '    operator: ok\n' +
+        '    expected: true\n' +
+        '    actual:   false\n' +
+        '    stack: |-\n' +
+        'Error: quiet mode should not display passed tests\n' +
+        'at Test.assert [as _assert] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:314:54)\n' +
+        'at Test.bound [as _assert] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Test.assert (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:433:10)\n' +
+        'at Test.bound [as true] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Test.<anonymous> (file:///var/home/aral/Projects/tap-monkey/tests/index.js:50:9)\n' +
+        'at Test.bound [as _cb] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Test.run (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:117:31)\n' +
+        'at Test.bound [as run] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/test.js:99:32)\n' +
+        'at Immediate.next [as _onImmediate] (/var/home/aral/Projects/tap-monkey/node_modules/tape/lib/results.js:88:19)\n' +
+        'at processImmediate (node:internal/timers:466:21)'
+    },
+    test: 2
+  }
+  
+  tapMonkey.failHandler(regularFailedAssertion)
+  tapMonkey.spinner.stop()
+  console.log = originalConsoleLog
+  
+  t.true(output.includes('operator: ok'), 'output should include operator')
+  t.true(output.includes('expected: true'), 'output should include expected field')
+  t.true(output.includes('actual  : false'), 'output should include actual field')
+
+  t.end()
+})
+
+//
+// Bail out handler tests.
+//
+
+test('bailout handler', t => {
+  // Setup.
+  const _error = console.error
+  let output = ''
+  console.error = string => output += string
+  
+  const _exit = process.exit
+  let exitCalledWithCorrectCode = false
+  process.exit = code => exitCalledWithCorrectCode = code === 1
+
+  // Test.
+  tapMonkey.spinner.start()
+  const mockRaw = 'mock raw event contents'
+  tapMonkey.bailOutHandler({ raw: mockRaw })
+  
+  t.strictEquals(tapMonkey.spinner.isSpinning, false, 'spinner has stopped')
+  t.true(output.includes(mockRaw), 'output includes mock event raw string')
+  t.true(exitCalledWithCorrectCode, 'exit is called')
+  
+  // Tear down.
+  console.error = _error
+  process.exit = _exit
+  
+  t.end()
+})
+
+//
+// Comment handler tests.
+//
+
+test('comment handler', t => {
+  // Setup.
+  const originalConsoleLog = console.log
+  const capturedConsoleLog = (...args) => output += args.join(' ')
+
+  console.log = capturedConsoleLog
+  let output = ''
+
+  // Test regular comment.
+  const regularCommentPrefix = '   🢂 '
+  const regularComment = 'a regular comment'
+
+  tapMonkey.commentHandler({ raw: regularComment })
+  tapMonkey.spinner.stop()
+  console.log = originalConsoleLog
+
+  t.equals(output, `${regularCommentPrefix} ${regularComment}`, 'regular comment is formatted correctly')
+  
+  // Test coverage comments.
+  output = ''
+  console.log = capturedConsoleLog
+  
+  const coverageTap = [
+    '----------|---------|----------|---------|---------|-----------------------',
+    '   File   | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s     ',
+    '----------|---------|----------|---------|---------|-----------------------',
+    'All files |   70.37 |    71.42 |      50 |   70.37 |                       ',
+    ' index.js |   70.37 |    71.42 |      50 |   70.37 | 59-61,105-131,135-152 ',
+    '----------|---------|----------|---------|---------|-----------------------'
+  ]
+  
+  const expectedCoverageOutput = '╭───────────┬─────────┬──────────┬─────────┬─────────┬────────────────────────╮│    File   │ % Stmts │ % Branch │ % Funcs │ % Lines │ Uncovered Line #s      │├───────────┼─────────┼──────────┼─────────┼─────────┼────────────────────────┤│ All files │   70.37 │    71.42 │      50 │   70.37 │                        ││  index.js │   70.37 │    71.42 │      50 │   70.37 │ 59─61,105─131,135─152  │╰───────────┴─────────┴──────────┴─────────┴─────────┴────────────────────────╯'
+  
+  coverageTap.forEach(line => {
+    tapMonkey.commentHandler({ raw: line })
+  })
+  tapMonkey.spinner.stop()
+  console.log = originalConsoleLog
+  
+  // Assertions.
+  t.equals(output.trim(), expectedCoverageOutput, 'formatted coverage output is correct')
+  
+  // Test too many borders in coverage error.
+  t.throws(() => {
+    tapMonkey.commentHandler({ raw: coverageTap[0] })
+  }, 'too many borders in coverage output error should throw')
+  
+  t.end()
+})
+
+//
+// Output handler tests.
+//
+
+test ('output handler', t => {
+  const vacuumPack = string => string.replace(/\s/g, '')
+  const originalConsoleLog = console.log
+  const capturedConsoleLog = (...args) => output += args.join(' ')
+
+  console.log = capturedConsoleLog
+  let output = ''
+  
+  // Test: all tests passing.
+
+  const mockAllTestsPassingResults = {
+    asserts: [1, 2, 3],
+    pass: [1, 2, 3],
+    fail: [] 
+  }  
+
+  tapMonkey.outputHandler(mockAllTestsPassingResults)
+  console.log = originalConsoleLog
+
+  t.strictEquals(tapMonkey.spinner.isSpinning, false, 'spinner has stopped')
+  t.true(vacuumPack(output).includes('Alltestspassing!Total3Passing3Failing0'))
+  
+  // Test: failing tests.
+  
+  output = ''
+  console.log = capturedConsoleLog
+  
+  const mockFailingTests = {
+    asserts: [1, 2, 3],
+    pass: [1],
+    fail: [2, 3] 
+  }
+  
+  tapMonkey.outputHandler(mockFailingTests)
+  console.log = originalConsoleLog
+  
+  t.true(vacuumPack(output).includes('Therearefailedtests.Total3Passing1Failing2'))
+  t.end()
+})
+