# snaptdout

> simple stdout snaptshot testing

Latest version **2.1.0** (published 2021-09-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install snaptdout
pnpm add snaptdout
yarn add snaptdout
bun add snaptdout
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2021-09-20 |
| First published | 2020-11-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Tal Hayut |
| Maintainers | tool3 |
| Keywords | snapshot-testing, cli, tests |

## Links

- npm: https://www.npmjs.com/package/snaptdout
- Repository: https://github.com/tool3/snaptdout
- Homepage: https://github.com/tool3/snaptdout#readme
- Issues: https://github.com/tool3/snaptdout/issues
- npm.io page: https://npm.io/package/snaptdout

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2021-09-20
- 2.0.0 — 2021-09-17
- 1.5.0 — 2021-07-28
- 1.4.1 — 2020-11-30
- 1.4.0 — 2020-11-30
- 1.3.3 — 2020-11-30
- 1.3.2 — 2020-11-28
- 1.3.1 — 2020-11-28
- 1.3.0 — 2020-11-28
- 1.2.1 — 2020-11-26
- 1.2.0 — 2020-11-26
- 1.1.2 — 2020-11-26
- 1.1.1 — 2020-11-26
- 1.1.0 — 2020-11-26
- 1.0.5 — 2020-11-26
- … 4 more at https://npm.io/package/snaptdout/versions

## README

# snaptdout
snaptdout is a lightweight, simple stdout snapshot testing with great diffs

# install
`npm i -D snaptdout`

# how does it work ?
snaptdout saves a copy of stdout to a `.json` file equivalent to the test file name, which should be committed to git.

# usage
snaptdout is a drop-in snapshot testing tool, you can use it in any testing framework by simply calling it with the expected `stdout`:

```javascript
describe('snapshot testing', () => {
    it('should snapshot stdout', async () => {
        const stdout = ` 
        this is a 
        complicated cli
        str ing
        `
        await snap(stdout, 'snapshot name');
    });
});
```

all consequential tests from this file will be compared to the snapshot.

> while snapshot name is optional, it is highly recommended.   
> if you do not provide a snapshot name, snaptdout will save the line and column of the running test as keys in the `.json` file.

# config 
you can provide config through your `package.json`, like so:

```json
...
"snaptdout": {
    "snapshotsDir": "relative/to/root/project/directory"
}
...
```

you can also provide the config as a third paremeter.
snapshot specific config overrides any global config.
```javascript
const stdout = '\x1b[32;7mHEY THERE\x1[0m';
await snap(stdout, 'hey', {ignoreAnsi: true});
```

##  `snapshotsDir`
snapshots directory.   
under this directory all snapshots files will be saved.

> default: test file location.

##  `snapshotsPrefix`
snapshots file prefix.   

> default: ''.

##  `ignoreAnsi`
ignore ansi formatting characters (`\x1b[32m` || `[32m`).   
if set to `true` - `snaptdout` will save the raw string without formatting and use that for future comparisons.   

> default: false.

##  `formattedOutput`
show formatted output after error message.   

> default: true.

# features
## lightweight
`snaptdout` has no dependencies, and a minimal footprint.

## 0 setup
you can simply `require` / `import` `snaptdout` and use it out of the box.

## simple.
`snaptdout` uses simple `.json` files to store the string we refer to as a `snapshot`.   
no binaries. nothing fancy.

## great diffs
when output based tests break, you need to know **exactly** where.   
[![](https://img.shields.io/static/v1?label=created%20with%20shellfie&message=📸&color=pink)](https://github.com/tool3/shellfie)   

![](./img/error.png)

# examples
yargs cli test example

```javascript
const {exec} = require('child_process');
const execute = require('util').promisify(exec);
const snap = require('snaptdout');

describe(('help test') => {
    it('should show the correct help text', async () => {
        const {stdout} = await execute('node index.js --help');
        await snap(stdout, 'help');
    });
});
```

ignore ansi characters for specific test

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