doctest-js

Let your documentation be your testing suite.

Write JSDoc style doc examples on all your functions and then test them using doctest-js.

Contents

Getting Started
Advanced
- Multiple tests
- Testing classes
Usage online
Contributing
Credits
Status

Getting Started

1. Install

npm install @supabase/doctest-js

2. Write @example comments

Create a JSDoc style @example on any functions that you want tested.

/**
 * Returns the sum of 2 numbers
 *
 * @example sum(1, 2)
 * //=> 3
 */
export const sum = (a, b) => {
  return a + b
}

Note that the expected return value must be prefixed by //=>.

3. Run the tests

Import the doctest function in your test suite and point it at the file.

import doctest from '@supabase/doctest-js';

describe('Doctests', () => {
  // file paths are relative to root of directory
  doctest('src/sum.js')
  doctest('src/someOtherFile.js')
})

Advanced

Multiple tests

You can run multiple tests for the same function.

/**
 * @example sum(1, 2)
 * //=> 3
 * @example sum(3, 4)
 * //=> 7
 */
export const sum = (a, b) => {
  return a + b
}

Testing classes

Testing classes requires you to pass a newed up instance of the class into the test itself. Here is a simple example:

// Arithmetic.js - a basic class which we need to test

class Arithmetic {
  constructor() {}

  /**
   * @example add(1, 2)
   * //=> 3
   */
  add(a, b) {
    return a + b
  }
}

export { Arithmetic }

// Arithmetic.test.js

const { Arithmetic } = require('./Arithmetic.js')

describe('passing doctest', () => {
  doctest('./Arithmetic.js', { instance: new Arithmetic() })
})