@supabase/doctest-js
v0.1.0
Published
Run doc examples as tests
Downloads
218
Maintainers
Keywords
Readme
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
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 doctests 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() });
});
FAQ's
Why isn't my test working?
Here are some tips:
Do I have to write @param, @returns etc?
The only JSDoc component you need is the @example
.
I have a long return value. Does it have to go on one line?
No. Example function calls and return values can span multiple lines but as mentioned above, it may cause problems (with the parser ... PR's welcome!).
Usage online
See this in the wild:
Contributing
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes and merge
Credits
- Inspired by Elixir Doctests
- Original fork of mainshayne223/doctest-js. See issue #1.