# jest-swag

> Jest plugin to provide auto-gen swagger document with api test

Latest version **0.0.2** (published 2020-04-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install jest-swag
pnpm add jest-swag
yarn add jest-swag
bun add jest-swag
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2020-04-19 |
| First published | 2020-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 996.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Philip Yu |
| Maintainers | seitk |

## Links

- npm: https://www.npmjs.com/package/jest-swag
- npm.io page: https://npm.io/package/jest-swag

## Dependencies (10)

- [qs](https://npm.io/package/qs.md) ^6.9.3
- [jest](https://npm.io/package/jest.md) ^25.3.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [express](https://npm.io/package/express.md) ^4.17.1
- [bluebird](https://npm.io/package/bluebird.md) ^3.7.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^9.0.0
- [supertest](https://npm.io/package/supertest.md) ^4.0.2
- [proper-lockfile](https://npm.io/package/proper-lockfile.md) ^4.1.1
- [swagger-ui-express](https://npm.io/package/swagger-ui-express.md) ^4.1.4
- [jest-environment-node](https://npm.io/package/jest-environment-node.md) ^25.3.0

## Recent versions

- 0.0.2 (latest) — 2020-04-19
- 0.0.1 — 2020-04-19

## README

# jest-swag

[![npm version](https://badge.fury.io/js/jest-swag.svg)](https://badge.fury.io/js/jest-swag)
[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](LICENSE)
  
## Installation
  
```bash
$ yarn add jest-swag
```
  
## Introduction
  
Inspired by [rswag](https://github.com/rswag/rswag), *jest-swag* is a Jest plugin to provide the tooling to
  
* Generate Open API specification (check [Example JSON](https://github.com/Seitk/jest-swag/blob/master/example/swagger.json) and [Screenshot](https://raw.githubusercontent.com/Seitk/jest-swag/master/assets/screenshot.png))
* Write along with your controller tests ([along with your test cases](https://github.com/Seitk/jest-swag/blob/master/example/test/Post-with-jest-swag.spec.js))
* Covering end-to-end testing from route to middleware to controller to view (powered by [supertest](https://github.com/visionmedia/supertest))
* And more in dev

### Example on a simple Posts and Comments API

Written with basic jest test cases:

```
describe('GET /posts', () => {
  it('responds with json', done => {
    request(app)
      .get('/posts')
      .expect('Content-Type', /json/)
      .expect(200)
      .then(res => {
        expect(res.body).toEqual({
          posts: [expect.objectContaining({ id: 'A0' })],
          total: 1,
        });
        done();
      });
  });
});
```

Written with jest-swag:

```
swag({ app }, s => {
  s.group({ name: 'Posts', description: 'Operations on posts' }, () => {
    s.api('GET /posts', { parameters: require('./swagger/parameters/paginate') }, () => {
      const expects = { 'Content-Type': /json/ };
      s.test('Success', 200, {
        expects,
        content: require('./swagger/responses/postsResponse'),
        then: res => {
          expect(res.body).toEqual({
            posts: [expect.objectContaining({ id: 'A0' })],
            total: 1,
          });
        },
      });
    });
  });
});
```

*jest-swag* provides a structure like the following  

```
swag({ app }, s => {
  s.group({ name: '...', description: '...' }, () => {
    s.api('GET /', {}, () => {
      s.test('...', 200, {
        then: () => {
          ... other test cases ...
        }
      });
    });
  });
});
```
  
`swag` creates the interface for adding api and tests
  
`s.group` defines the swagger group of APIs
  
`s.api` defines a route with the input parameters
  
`s.test` defines a response with code and example, it will also includes a basic test with supertest

More example usages on:
  
https://github.com/Seitk/jest-swag/blob/master/example/test
  
## Quick Start
  
Edit your `package.json` to change configurations under `jest`:  
  
https://github.com/Seitk/jest-swag/blob/master/example/package.json
  
1. Change `testEnvironment` to `"jest-swag/environment"`
2. Add `jest-swag/setup` to `setupFilesAfterEnv`
3. Add `jest-swag/reporter` to `reporters`
4. Add `jest-swag` for specifying basic configuration on swagger schema
```
"jest-swag": {
  "schema": {
    "openapi": "3.0.0",
    "info": {
      "title": "Example API",
      "description": "An example on using jest-swag to generate api docs with jest test",
      "version": "1.0.0"
    },
    "host": "example.com",
    "schemes": [
      "http"
    ]
  }
},
```
    
Start writing tests with `swag` and run `jest`:

```bash
% yarn test
yarn run v1.21.1
$ jest
 PASS  test/Comment-with-jest-swag.spec.js
 PASS  test/Post-with-jest-swag.spec.js
 PASS  test/Post.spec.js

Test Suites: 3 passed, 3 total
Tests:       13 passed, 13 total
Snapshots:   0 total
Time:        1.116s
Ran all test suites.
[jest-swag] swagger specification generated to swagger.json
✨  Done in 1.85s.
```
  
The output file will be generated to the directory path, lift up api doc with [swagger-ui](https://www.npmjs.com/package/swagger-ui-express)
  
## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/jest-swag · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._