doctest-js - GitLite

KO | EN

gitlite — search

#hacktoberfest #llm #machine-learning #rust #deep-learning #linux #nodejs #awesome #cli #kubernetes #security #pytorch #mcp #openai

doctest-js

(★ 104)

Run JSDoc style doc examples as tests within your test suite

File Explorer

Download Latest Version (.zip)

- - ci.yml
- FUNDING.yml
- index.js
- doctest.js
- doctest_parser.js
- index.js
- safe_eval.js
- - sample_error_module.js
  - sample_failing_module.js
  - sample_passing_class.js
  - sample_passing_module.js
- doctest_parser_test.js
- doctest_test.js
- safe_eval_test.js
.babelrc
.eslintignore
.eslintrc
.gitignore
.prettierignore
.prettierrc
LICENSE
package-lock.json
package.json
README.md
webpack.config.js

# Installation Guide

1. Get the code

git clone https://github.com/kiwicopple/doctest-js

Downloads the entire project code from GitHub to your computer.

cd doctest-js

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install @supabase/doctest-js

Downloads and installs the libraries listed in package.json.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# doctest-js

Let your documentation be your testing suite.

Write [JSDoc](http://usejsdoc.org/about-getting-started.html) style doc examples on all your functions and then test them using `doctest-js`.

**Contents**

- [Getting Started](#getting-started)
  - [1. Install](#1-install)
  - [2. Write @example comments](#2-write-example-comments)
  - [3. Run the tests](#3-run-the-tests)
- [Advanced](#advanced)
  - [Multiple tests](#multiple-tests)
  - [Testing classes](#testing-classes)
- [Usage online](#usage-online)
- [Contributing](#contributing)
- [Credits](#credits)
- [Status](#status)

## Getting Started

### 1. Install

```sh
npm install @supabase/doctest-js
```

### 2. Write @example comments

Create a [JSDoc style @example](https://jsdoc.app/tags-example.html) on any functions that you want tested.

```javascript
/**
 * 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.

```javascript
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.

```javascript
/**
 * @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:

```js
// 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 }
```

```js
// Arithmetic.test.js

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

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

## Usage online

See this in the wild:

- [supabase/postgrest-js](https://github.com/supabase/postgrest-js/blob/master/test/unit/Doctests.test.js)

## 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](https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html)
* Original fork of [mainshayne223/doctest-js](https://github.com/MainShayne233/js-doctest). See [issue #1](https://github.com/MainShayne233/js-doctest/issues/1).

## Status

Ready for production! Watch and star this repo to keep updated on releases.

![Watch this repo](https://gitcdn.xyz/repo/supabase/monorepo/master/web/static/watch-repo.gif "Watch this repo")

## Sponsors

We are building the features of Firebase using enterprise-grade, open source products. We support existing communities wherever possible, and if the products don’t exist we build them and open source them ourselves. Thanks to these sponsors who are making the OSS ecosystem better for everyone.

[![Worklife VC](https://user-images.githubusercontent.com/10214025/90451355-34d71200-e11e-11ea-81f9-1592fd1e9146.png)](https://www.worklife.vc)
[![New Sponsor](https://user-images.githubusercontent.com/10214025/90518111-e74bbb00-e198-11ea-8f88-c9e3c1aa4b5b.png)](https://github.com/sponsors/supabase)