js-build-tools 1.2.2 → 2.1.0

package/functions/partials/distFor.test.js

@@ -0,0 +1,125 @@
+const fs = require('fs')
+const setUp = require('../test-helpers/setUp')
+setUp.setDefaults('test-dist-for')
+const gulpConfig = setUp.gulpConfig
+const distFor = require('./distFor')
+const { countMatches } = require('../testHelpers')
+const typeScript = require('../typeScript')
+
+const rawContents = 'const babel = require(\'gulp-babel\')\n' +
+  'const { dest, src } = require(\'gulp\')\n' +
+  'const typeScript = require(\'./typeScript\')\n' +
+  'const gulpConfig = require(\'../gulp.config.js\')\n' +
+  '\n' +
+  'const useTsConfig = gulpConfig.get(\'useTsConfig\')\n' +
+  '\n' +
+  'const defaultSrc = useTsConfig\n' +
+  '  ? gulpConfig.get(\'distSearch\')\n' +
+  '  : gulpConfig.get(\'srcSearch\')\n' +
+  '\n' +
+  'const distFor = (srcPath = defaultSrc, destPath = gulpConfig.get(\'distPath\')) => {\n' +
+  '  let pipedSrc = src(srcPath)\n' +
+  '  if (useTsConfig) {\n' +
+  '    // Add the typescript so we can compile then apply babel to those files\n' +
+  '    pipedSrc = typeScript(pipedSrc)\n' +
+  '  }\n' +
+  '  return pipedSrc\n' +
+  '    .pipe(babel())\n' +
+  '    .pipe(dest(destPath))\n' +
+  '}\n' +
+  '\n' +
+  'module.exports = distFor\n'
+
+const rawTsContents = '// @ts-ignore\n' +
+  'import gulpConfig from \'../gulp.config.js\'\n' +
+  '// @ts-ignore\n' +
+  'import typeScript from \'./typeScript.js\'\n' +
+  '// @ts-ignore\n' +
+  'import {dest, src} from \'gulp\'\n' +
+  '// @ts-ignore\n' +
+  'import babel from \'gulp-babel\'\n' +
+  '\n' +
+  'const useTsConfig = gulpConfig.get(\'useTsConfig\')\n' +
+  '\n' +
+  'const defaultSrc: string | Array<any> = useTsConfig\n' +
+  '    ? gulpConfig.get(\'distSearch\')\n' +
+  '    : gulpConfig.get(\'srcSearch\')\n' +
+  '\n' +
+  '// @ts-ignore\n' +
+  'const distFor = (srcPath: string | Array<any> = defaultSrc, destPath: string = gulpConfig.get(\'distPath\')): import(\'readable-stream\').Stream => {\n' +
+  '    let pipedSrc = src(srcPath)\n' +
+  '    if (useTsConfig) {\n' +
+  '        // Add the typescript so we can compile then apply babel to those files\n' +
+  '        pipedSrc = typeScript(pipedSrc)\n' +
+  '    }\n' +
+  '    return pipedSrc\n' +
+  '        .pipe(babel())\n' +
+  '        .pipe(dest(destPath))\n' +
+  '}\n' +
+  '\n' +
+  'export default distFor\n'
+
+beforeEach(setUp.beforeEach)
+
+afterEach(setUp.afterEach)
+
+describe('distFor', () => {
+  test('copies the src directory and babelifies it into the dist directory', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const srcFile = `${srcPath}/distFor.js`
+    fs.writeFileSync(srcFile, rawContents)
+    expect.assertions(7)
+    const oldContents = fs.readFileSync(srcFile).toString()
+    expect(countMatches(oldContents, 'const ')).toEqual(7)
+    const distPath = gulpConfig.get('distPath')
+    distFor(srcFile)
+      .on('finish', () => {
+        expect(fs.existsSync(distPath)).toBeTruthy()
+        const babelifiedContents = fs.readFileSync(`${distPath}/distFor.js`).toString()
+        expect(countMatches(babelifiedContents, '"use strict"')).toEqual(1)
+        // If the below assertion fails it is because 'const' no longer is replaced with 'var'
+        // To fix, change `.browserslistrc` set `> 0.24%` to a lower number. For example, last fix changed from `> 0.25%`
+        expect(countMatches(babelifiedContents, 'const ')).toEqual(0)
+        expect(countMatches(babelifiedContents, 'var ')).toEqual(10)
+        expect(countMatches(babelifiedContents, 'function')).toEqual(1)
+        expect(countMatches(babelifiedContents, 'arguments')).toEqual(6)
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  })
+
+  test('can process typescript before babel', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const srcFile = `${srcPath}/distFor.ts`
+    fs.writeFileSync(srcFile, rawTsContents)
+    expect.assertions(7)
+    const oldContents = fs.readFileSync(srcFile).toString()
+    expect(countMatches(oldContents, 'const ')).toEqual(3)
+    const distPath = gulpConfig.get('distPath')
+    typeScript()
+      .on('finish', () => {
+        distFor()
+          .on('finish', () => {
+            expect(fs.existsSync(distPath)).toBeTruthy()
+            const babelifiedContents = fs.readFileSync(`${distPath}/distFor.js`).toString()
+            expect(countMatches(babelifiedContents, '"use strict"')).toEqual(1)
+            expect(countMatches(babelifiedContents, 'const ')).toEqual(0)
+            expect(countMatches(babelifiedContents, 'var ')).toEqual(8)
+            expect(countMatches(babelifiedContents, 'function')).toEqual(1)
+            expect(countMatches(babelifiedContents, 'Object.defineProperty(exports, "__esModule", { value: true })')).toEqual(1)
+            done()
+          })
+          .on('error', error => {
+            console.error('Encountered error with distFor', error)
+            done()
+          })
+      })
+      .on('error', error => {
+        console.error('Encountered error with typeScript', error)
+        done()
+      })
+  }, 30000)
+})

package/functions/partials/distForSrc.js

@@ -0,0 +1,14 @@
+const gulpConfig = require('../../gulp.config')
+
+/**
+ * Retrieve the correct distFor search path based on TS Config.
+ * @function
+ * @memberOf module:partials
+ * @param {module:gulpConfig~FlagStringSetting} [useTs='config/for/ts']
+ * @returns {string}
+ */
+const distForSrc = (useTs = gulpConfig.get('useTsConfig')) => useTs
+  ? gulpConfig.get('distSearch')
+  : gulpConfig.get('srcSearch')
+
+module.exports = distForSrc

package/functions/partials/distForSrc.test.js

@@ -0,0 +1,17 @@
+const setUp = require('../test-helpers/setUp')
+const gulpConfig = setUp.gulpConfig
+const distForSrc = require('./distForSrc')
+
+describe('distForSrc', () => {
+  test('useTsConfig as false returns srcSearch', () => {
+    expect.assertions(1)
+    gulpConfig.set('useTsConfig', false)
+    expect(distForSrc()).toBe(gulpConfig.get('srcSearch'))
+  })
+
+  test('useTsConfig as true returns distSearch', () => {
+    expect.assertions(1)
+    gulpConfig.set('useTsConfig', true)
+    expect(distForSrc()).toBe(gulpConfig.get('distSearch'))
+  })
+})

package/functions/partials/distSeries.js

@@ -0,0 +1,21 @@
+const gulpConfig = require('../../gulp.config')
+const distFor = require('./distFor')
+const distForSrc = require('./distForSrc')
+const { series } = require('gulp')
+const tsFor = require('./tsFor')
+
+/**
+ * When using TypeScript, ensure that we process the ts first then run babel (dist)
+ * @function
+ * @memberOf module:partials
+ * @param {string} [srcPath='src/config/path/dist/for']
+ * @param {string} [distFinalPath='dist/config/path']
+ * @param {string} [tsSearch='ts/search/config/path']
+ * @returns {Function}
+ */
+const distSeries = (srcPath = distForSrc(), distFinalPath = gulpConfig.get('distPath'), tsSearch = gulpConfig.get('tsSearch')) =>
+  gulpConfig.get('useTsConfig')
+    ? series(() => tsFor(tsSearch, distFinalPath), () => distFor(srcPath, distFinalPath))
+    : () => distFor(srcPath, distFinalPath)
+
+module.exports = distSeries

package/functions/partials/distSeries.test.js

@@ -0,0 +1,33 @@
+const setUp = require('../test-helpers/setUp')
+const gulpConfig = setUp.gulpConfig
+const distSeries = require('./distSeries')
+const tsFor = require('./tsFor')
+const distFor = require('./distFor')
+
+const genericFunction = () => Promise.resolve(true)
+
+jest.mock('./distFor', () => jest.fn(genericFunction))
+jest.mock('./tsFor', () => jest.fn(genericFunction))
+
+describe('distSeries', () => {
+  test('when not using ts config only returns runnable distFor', done => {
+    gulpConfig.set('useTsConfig', false)
+    expect.assertions(1)
+    distSeries()()
+    setTimeout(() => {
+      expect(distFor).toHaveBeenCalledWith(gulpConfig.get('srcSearch'), gulpConfig.get('distPath'))
+      done()
+    }, 500)
+  })
+
+  test('when using ts config returns runnable series of tsFor and distFor', done => {
+    gulpConfig.set('useTsConfig', true)
+    expect.assertions(2)
+    distSeries()()
+    setTimeout(() => {
+      expect(tsFor).toHaveBeenCalledWith(gulpConfig.get('tsSearch'), gulpConfig.get('distPath'))
+      expect(distFor).toHaveBeenCalledWith(gulpConfig.get('distSearch'), gulpConfig.get('distPath'))
+      done()
+    }, 500)
+  })
+})

package/functions/partials/minifyFor.js

@@ -0,0 +1,16 @@
+const { dest, src } = require('gulp')
+const { default: uglify } = require('gulp-uglify-es')
+const rename = require('gulp-rename')
+
+/**
+ * Minify files and rename the output with '.min' extension.
+ * @function
+ * @memberOf module:partials
+ * @returns {*}
+ */
+const minifyFor = (srcSearch, destination) => src(srcSearch)
+  .pipe(uglify())
+  .pipe(rename({ extname: '.min.js' }))
+  .pipe(dest(destination))
+
+module.exports = minifyFor

package/functions/partials/minifyFor.test.js

@@ -0,0 +1,48 @@
+const fs = require('fs')
+const setUp = require('../test-helpers/setUp')
+setUp.setDefaults('test-minify-for')
+const gulpConfig = setUp.gulpConfig
+const minifyFor = require('./minifyFor')
+const { countMatches } = require('../testHelpers')
+
+const rawContents = 'const { dest, src } = require(\'gulp\')\n' +
+  'const { default: uglify } = require(\'gulp-uglify-es\')\n' +
+  'const rename = require(\'gulp-rename\')\n' +
+  '\n' +
+  '/**\n' +
+  ' * Minify files and rename the output with \'.min\' extension.\n' +
+  ' * @returns {*}\n' +
+  ' */\n' +
+  'const minifyFor = (srcSearch, destination) => src(srcSearch)\n' +
+  '  .pipe(uglify())\n' +
+  '  .pipe(rename({ extname: \'.min.js\' }))\n' +
+  '  .pipe(dest(destination))\n' +
+  '\n' +
+  'module.exports = minifyFor\n'
+
+beforeEach(() => setUp.beforeEach()
+  .then(() => fs.writeFileSync(gulpConfig.get('srcPath') + '/minifyFor.js', rawContents)))
+
+afterEach(setUp.afterEach)
+
+describe('minifyFor', () => {
+  test('copies the src directory and minifies it into the dist directory with min extension', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const filePath = `${srcPath}/minifyFor.js`
+    const expectedFilePath = `${srcPath}/minifyFor.min.js`
+    expect.assertions(3)
+    const oldContents = fs.readFileSync(filePath).toString()
+    expect(countMatches(oldContents, '\n')).toBe(14)
+    minifyFor(filePath, srcPath)
+      .on('finish', () => {
+        expect(fs.existsSync(expectedFilePath)).toBeTruthy()
+        const minifiedContents = fs.readFileSync(expectedFilePath).toString()
+        expect(countMatches(minifiedContents, '\n')).toBe(0)
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  })
+})

package/functions/partials/readmeTemplate.js

@@ -0,0 +1,15 @@
+const { dest, src } = require('gulp')
+const gulpConfig = require('../../gulp.config.js')
+const rename = require('gulp-rename')
+
+/**
+ * Copy a readme template into the README.md file.
+ * @function
+ * @memberOf module:partials
+ * @returns {*}
+ */
+const readmeTemplate = () => src(gulpConfig.get('readmeTemplate'))
+  .pipe(rename(gulpConfig.get('readmeFile')))
+  .pipe(dest(gulpConfig.get('readmePath')))
+
+module.exports = readmeTemplate

package/functions/partials/readmeTemplate.test.js

@@ -0,0 +1,33 @@
+const fs = require('fs')
+const setUp = require('../test-helpers/setUp')
+setUp.setDefaults('test-readme-template')
+const gulpConfig = setUp.gulpConfig
+const readmeTemplate = require('./readmeTemplate')
+
+const mainMd = 'MAIN.md'
+const mainTestPath = gulpConfig.get('readmeTemplate')
+
+beforeEach(() => setUp.beforeEach()
+  .then(() => fs.copyFileSync(mainMd, mainTestPath)))
+
+afterEach(setUp.afterEach)
+
+describe('readmeTemplate', () => {
+  test('copies the main contents into the new README.md', done => {
+    const readmeFilePath = gulpConfig.get('readmePath') + gulpConfig.get('readmeFile')
+    const mainContents = fs.readFileSync(mainTestPath)
+    expect.assertions(2)
+    readmeTemplate()
+      .on('finish', async () => {
+        await expect(fs.existsSync(readmeFilePath)).toBeTruthy()
+        const readme = await fs.readFileSync(readmeFilePath)
+        // Confirm that the contents for MAIN.md are copied to README.md
+        await expect(readme).toEqual(mainContents)
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  })
+})

package/functions/partials/runOnChange.js

@@ -0,0 +1,57 @@
+const gulpConfig = require('../../gulp.config.js')
+const bundle = require('../bundle')
+const distSeries = require('./distSeries')
+const { parallel, series } = require('gulp')
+const testQuick = require('../testQuick')
+
+/**
+ * Run this function when the watched files are modified.
+ * 1. Find the sub-folders within src path
+ * 2. Maintain the folders, but use distPath for base
+ * 3. Remove base folder and return dist path with correct sub-folders
+ * @example
+ * // Configured paths
+ * distPath = 'dist'
+ * srcPath = 'functions'
+ *
+ * // Path parameter
+ * path = 'functions/some/path/file.js'
+ *
+ * // Generated regex using configured srcPath
+ * pathRegex = '/^functions(.*\/).+\.js$/i'
+ *
+ * // Replace value using the configured distPath
+ * replacePath = 'dist$1'
+ *
+ * // The resulting replaced path for the destination folder
+ * distPathResult = 'dist/some/path/'
+ * @function
+ * @memberOf module:partials
+ * @param {string} path
+ * @returns {stream.Stream}
+ */
+const runOnChange = path => {
+  const useTs = gulpConfig.get('useTsConfig')
+  const distPath = gulpConfig.get('distPath')
+  const srcPath = gulpConfig.get('srcPath')
+  /**
+   * 1. The original path comes in from src and is a .ts
+   * 2. Discover the outgoing dist path where that file should go
+   * 3. Use the path and dist in tsFor
+   * 4. Take the original path, convert to full file path in dist
+   * 5. Use the dist path found previously in #2
+   * 6. Use the full dist path and the dist outgoing path in distFor
+   */
+  const pathRegex = new RegExp(`^${srcPath}(.*\\/)(.+)\\.(js|ts)$`, 'i')
+  const distPathResult = path.replace(pathRegex, `${distPath}$1`)
+  let distSrcPath = path
+  if (useTs) {
+    distSrcPath = path.replace(pathRegex, `${distPath}$1$2.js`)
+  }
+  const runSeries = distSeries(distSrcPath, distPathResult, path)
+  return gulpConfig.get('nodeOnly')
+    ? series(testQuick, runSeries)()
+    : parallel(testQuick, series(runSeries, bundle))()
+}
+
+module.exports = runOnChange

package/functions/partials/runOnChange.test.js

@@ -0,0 +1,93 @@
+const fs = require('fs')
+const setUp = require('../test-helpers/setUp')
+setUp.setDefaults('test-run-on-change')
+const gulpConfig = setUp.gulpConfig
+const bundle = require('../bundle')
+const distFor = require('./distFor')
+const runOnChange = require('./runOnChange')
+const tsFor = require('./tsFor')
+const testQuick = require('../testQuick')
+
+const genericFunction = () => Promise.resolve(true)
+
+jest.mock('../bundle', () => jest.fn(genericFunction))
+jest.mock('./distFor', () => jest.fn(genericFunction))
+jest.mock('./tsFor', () => jest.fn(genericFunction))
+jest.mock('../testQuick', () => jest.fn(genericFunction))
+
+const rawContents = 'export function sayHello(name: string) {\n' +
+  '  return `Hello from ${name}`;\n' +
+  '}'
+
+const distPath = gulpConfig.get('distPath') + '/'
+const srcPath = gulpConfig.get('srcPath')
+const srcFile = `${srcPath}/runOnChange.js`
+const srcTsFile = `${srcPath}/runOnChange.ts`
+
+beforeEach(() => {
+    return setUp.beforeEach()
+      .then(() => fs.writeFileSync(srcTsFile, rawContents))
+      .then(() => fs.writeFileSync(srcFile, rawContents))
+  }
+)
+
+afterEach(() => {
+  jest.clearAllMocks()
+  return setUp.afterEach()
+})
+
+describe('runOnChange', () => {
+  test('runs testQuick and distFor for nodeOnly true and useTs false', done => {
+    gulpConfig.set('nodeOnly', true)
+    gulpConfig.set('useTsConfig', false)
+    expect.assertions(2)
+    runOnChange(srcFile)
+    setTimeout(() => {
+      expect(testQuick).toHaveBeenCalled()
+      expect(distFor).toHaveBeenCalledWith(srcFile, distPath)
+      done()
+    }, 500)
+  })
+
+  test('runs testQuick and distFor for nodeOnly true and tsFor for useTs true', done => {
+    gulpConfig.set('nodeOnly', true)
+    gulpConfig.set('useTsConfig', true)
+    const distSrcPath = distPath + 'runOnChange.js'
+    expect.assertions(3)
+    runOnChange(srcTsFile)
+    setTimeout(() => {
+      expect(testQuick).toHaveBeenCalled()
+      expect(tsFor).toHaveBeenCalledWith(srcTsFile, distPath)
+      expect(distFor).toHaveBeenCalledWith(distSrcPath, distPath)
+      done()
+    }, 500)
+  })
+
+  test('runs testQuick and distFor then bundle for nodeOnly false and useTs false', done => {
+    gulpConfig.set('nodeOnly', false)
+    gulpConfig.set('useTsConfig', false)
+    expect.assertions(3)
+    runOnChange(srcFile)
+    setTimeout(() => {
+      expect(testQuick).toHaveBeenCalled()
+      expect(distFor).toHaveBeenCalledWith(srcFile, distPath)
+      expect(bundle).toHaveBeenCalled()
+      done()
+    }, 500)
+  })
+
+  test('runs testQuick and distFor then bundle for nodeOnly false and tsFor for useTs true', done => {
+    gulpConfig.set('nodeOnly', false)
+    gulpConfig.set('useTsConfig', true)
+    const distSrcPath = distPath + 'runOnChange.js'
+    expect.assertions(4)
+    runOnChange(srcTsFile)
+    setTimeout(() => {
+      expect(testQuick).toHaveBeenCalled()
+      expect(tsFor).toHaveBeenCalledWith(srcTsFile, distPath)
+      expect(distFor).toHaveBeenCalledWith(distSrcPath, distPath)
+      expect(bundle).toHaveBeenCalled()
+      done()
+    }, 500)
+  })
+})

package/functions/partials/tsFor.js

@@ -0,0 +1,21 @@
+const { dest, src } = require('gulp')
+const gulpConfig = require('../../gulp.config.js')
+const ts = require('gulp-typescript')
+
+const tsProject = ts.createProject(gulpConfig.get('useTsConfig'))
+
+/**
+ * Starting at the source directory, find all the ts files and convert them into the distribution directory.
+ * @function
+ * @memberOf module:partials
+ * @param {string|array} [srcPath='']
+ * @param {string} [distPath='']
+ * @returns {stream.Stream}
+ * @see `https://www.typescriptlang.org/docs/handbook/gulp.html` for more info
+ */
+const tsFor = (srcPath = gulpConfig.get('tsSearch'), distPath = gulpConfig.get('distPath')) => src(srcPath)
+  .pipe(tsProject())
+  .js
+  .pipe(dest(distPath))
+
+module.exports = tsFor

package/functions/partials/tsFor.test.js

@@ -0,0 +1,44 @@
+const fs = require('fs')
+const setUp = require('../test-helpers/setUp')
+setUp.setDefaults('test-ts-for')
+const gulpConfig = setUp.gulpConfig
+const tsFor = require('./tsFor')
+const { countMatches, logObject } = require('../testHelpers')
+
+const rawContents = 'export function sayHello(name: string) {\n' +
+  '  return `Hello from ${name}`;\n' +
+  '}'
+
+beforeEach(
+  () => setUp.beforeEach()
+    .then(
+      async () => {
+        const srcPath = gulpConfig.get('srcPath')
+        return fs.writeFileSync(`${srcPath}/typeScript.ts`, rawContents)
+      }
+    )
+)
+
+afterEach(setUp.afterEach)
+
+describe('tsFor', () => {
+  test('copies the src directory and compiles it into the dist directory', done => {
+    const distPath = gulpConfig.get('distPath')
+    const srcPath = gulpConfig.get('srcPath')
+    const srcFile = `${srcPath}/typeScript.ts`
+    expect.assertions(3)
+    const oldContents = fs.readFileSync(srcFile).toString()
+    expect(countMatches(oldContents, 'sayHello(name: string)')).toEqual(1)
+    tsFor(srcFile, distPath)
+      .on('finish', () => {
+        expect(fs.existsSync(distPath)).toBeTruthy()
+        const compiledContents = fs.readFileSync(`${distPath}/typeScript.js`).toString()
+        expect(countMatches(compiledContents, 'sayHello(name)')).toEqual(1)
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  }, 30000)
+})

package/functions/partials.js

@@ -0,0 +1,32 @@
+/**
+ * Micro-functions used as components for the main gulp functions.
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 2.0.0
+ * @module partials
+ * @memberOf module:js-build-tools
+ */
+
+const addToReadme = require('./partials/addToReadme')
+const beginWatcher = require('./partials/beginWatcher')
+const clean = require('./partials/clean')
+const distFor = require('./partials/distFor')
+const distForSrc = require('./partials/distForSrc')
+const distSeries = require('./partials/distSeries')
+const minifyFor = require('./partials/minifyFor')
+const readmeTemplate = require('./partials/readmeTemplate')
+const runOnChange = require('./partials/runOnChange')
+const tsFor = require('./partials/tsFor')
+
+module.exports = {
+  addToReadme,
+  beginWatcher,
+  clean,
+  distFor,
+  distForSrc,
+  distSeries,
+  minifyFor,
+  readmeTemplate,
+  runOnChange,
+  tsFor,
+}

package/functions/partials.test.js

@@ -0,0 +1,7 @@
+const partials = require('./partials')
+
+describe('partials', () => {
+  test('is object with all partial exports', () => {
+    expect(Object.keys(partials).length).toBe(10)
+  })
+})

package/functions/test-helpers/circularObject.js

@@ -0,0 +1,28 @@
+/**
+ * Multilayered node tree-like structure with parent references
+ * @memberOf module:testHelpers
+ * @type {Object.<string, string|Object|Array>}
+ */
+const circularObject = { name: 'root', parent: {}, body: {}, head: {}, children: [] }
+circularObject.children = [
+  { name: 'body', parent: {}, children: [] },
+  { name: 'head', parent: {}, children: [] }
+]
+circularObject.body = circularObject.children[0]
+circularObject.head = circularObject.children[1]
+circularObject.body.parent = circularObject
+circularObject.head.parent = circularObject
+circularObject.body.children = [
+  { name: 'body child one', parent: {}, children: [] },
+  { name: 'body child two', parent: {}, children: [] }
+]
+circularObject.body.children[0].parent = circularObject.body
+circularObject.body.children[1].parent = circularObject.body
+circularObject.head.children = [
+  { name: 'head child one', parent: {}, children: [] },
+  { name: 'head child two', parent: {}, children: [] }
+]
+circularObject.head.children[0].parent = circularObject.head
+circularObject.head.children[1].parent = circularObject.head
+
+module.exports = circularObject

package/functions/test-helpers/circularObject.test.js

@@ -0,0 +1,14 @@
+import circularObject from './circularObject'
+
+describe('circularObject', () => {
+  test('has sample circular object', () => {
+    expect(circularObject.body.parent).toBe(circularObject)
+    expect(circularObject.body.children[0].parent).toBe(circularObject.body)
+    expect(circularObject.body.children[1].parent).toBe(circularObject.body)
+    expect(circularObject.children[0]).toBe(circularObject.body)
+    expect(circularObject.head.parent).toBe(circularObject)
+    expect(circularObject.head.children[0].parent).toBe(circularObject.head)
+    expect(circularObject.head.children[1].parent).toBe(circularObject.head)
+    expect(circularObject.children[1]).toBe(circularObject.head)
+  })
+})

package/functions/test-helpers/countMatches.js

@@ -0,0 +1,11 @@
+/**
+ * Simple way to count string occurrences for testing.
+ * @function
+ * @memberOf module:testHelpers
+ * @param {string} content
+ * @param {string} search
+ * @returns {number}
+ */
+const countMatches = (content, search) => content.split(search).length - 1
+
+module.exports =  countMatches

package/functions/test-helpers/countMatches.test.js

@@ -0,0 +1,9 @@
+const countMatches = require('./countMatches')
+
+describe('countMatches', () => {
+  test('can get count of string occurrences', () => {
+    const find = 'find me'
+    const sampleString = `${find} in some string that could change the times ${find} will occur here, ${find} should be found three times`
+    expect(countMatches(sampleString, find)).toBe(3)
+  })
+})