<commit_before>---
title: Getting Started
section: 1
redirect_from:
  - /docs/
  - /docs
  - /basics/
  - /basics
---

# Getting Started

## tap includes out of the box:

`tap` includes out of the box:

1. [A test framework](/docs/api/) for writing tests in Node.js.
2. [A command-line interface](/docs/cli/) for running tests and reporting on their
   success or failure.
3. [Support for test-coverage](/docs/coverage/), including coverage of child
   processes spawned in the process of testing.
4. [Support for parallel tests](/docs/api/parallel-tests/), including running some tests in
   parallel, and others serially.

See [the changelog](/changelog/) for recent updates, or just get started with the basics down below.

[![Build Status](https://travis-ci.org/tapjs/node-tap.svg?branch=master)](https://travis-ci.org/tapjs/node-tap)

## tap basics

This tutorial will teach you just enough to get up and running with tap in your
Node.js programs.

## install tap

Use npm to install tap:

```bash
npm install tap --save-dev
```

The `save-dev` part makes it saved to your package.json's `devDependencies`
list instead of as a regular dependency.

Next, update your package.json so that the test script invokes tap:

```json
{
  "name": "my-awesome-module",
  "version": "1.2.3",
  "devDependencies": {
    "tap": "^13.0.0"
  },

  "scripts": {
    "test": "tap"
  }
}
```

## test files

Create a folder for your tests.  Call the folder `test` so that people
can guess what it's for:

```bash
mkdir test/
```

It's a good practice to break up a big test suite into multiple files.
Each file should cover a feature or concept.  For small Node modules,
often a single test file is enough.

I usually call the first one `test/basic.js`, because it covers the
basic functionality.

By default, when you run `tap` with no arguments, it'll run any files in the
`test` directory, as well as any files than end in `*.spec.js` or `*.test.js`.
If you want to run a specific file, you can also put it on the command line
directly:

```bash
tap test/foo.js
```

## "hello world" test program

The root tap object is a member of tap's `Test` class.  That means it
has all the same properties as child tests.

Here's a very basic test program:

```javascript
// test/hello-world.js
const tap = require('tap')
tap.pass('this is fine')
```

If we run this with node, we'll see the raw TAP output:

```bash
$ node test/hello-world.js
```

```tap
TAP version 13
ok 1 - this is fine
1..1
# time=26.792ms
```

You can always run a tap test program directly to see what it is
doing.  This is especially handy in debugging test failures

That output is "TAP" or "Test Anything Protocol".  It has a long
history in the Perl community, and there are many tools in many
languages that can generate and parse this format.

Node-tap is one of those tools, so let's have it create something
prettier for us.  Because we installed tap as a devDependency, and
added it as a script in package.json, we can run `npm test` to run all
our tests with the `tap` built-in cli.

<pre class="language-text"><code class="language-text">
$ npm test

> my-awesome-module@1.2.3 test /Users/isaacs/dev/js/tap/docs/static/my-awesome-module
> tap

<span style="background:#0f0;color:#000;padding-top:2px"> PASS </span> test/hello-world.js <b style="color:#fff">1</b> <span style="color:#0f0">OK</span> <b style="color:#999">1s</b>

<div style="background:#fff;color:#111;width:29ex">
  🌈 SUMMARY RESULTS 🌈

</div>
<b>Suites:</b>   <span style="color:#0f0">1 passed</span>, 1 of 1 completed
<b>Asserts:</b>  <span style="color:#0f0">1 passed</span>, of 1
<b style="color:#999">Time:     1s</b>
----------|----------|----------|----------|----------|-------------------|
File      |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
----------|----------|----------|----------|----------|-------------------|
All files |        0 |        0 |        0 |        0 |                   |
----------|----------|----------|----------|----------|-------------------|
</code></pre>

## coverage

Test coverage makes it a lot easier to know that we're testing what we
think we're testing.

So, let's create a module to test.  Let's say that we want a function
that returns 'even' if the number is even, or 'odd' if it's odd,
unless it's greater than 100, in which case it should return 'big',
and if it's less than 0, it should return 'negative'.

```javascript
// my-awesome-module.js
module.exports = x => {
  if (x % 2 === 0) {
    return 'even'
  } else if (x % 2 === 1) {
    return 'odd'
  } else if (x > 100) {
    return 'big'
  } else if (x < 0) {
    return 'negative'
  }
}
```

Probably no bugs!

Now, we can create a test file that pulls it in and verifies the
result:

```javascript
// test/basic.js
const tap = require('tap')
const mam = require('../my-awesome-module.js')

// Always call as (found, wanted) by convention
tap.equal(mam(1), 'odd')
tap.equal(mam(2), 'even')
```

Looks good to me!

<pre class="language-text"><code class="language-text">
$ npm test

> my-awesome-module@1.2.3 test /Users/isaacs/dev/js/tap/docs/static/my-awesome-module
> tap

<span style="background:#0f0;color:#000;padding-top:2px"> PASS </span> test/basic.js <b style="color:#fff">2</b> <span style="color:#0f0">OK</span> <b style="color:#999">1s</b>
<span style="background:#0f0;color:#000;padding-top:2px"> PASS </span> test/hello-world.js <b style="color:#fff">1</b> <span style="color:#0f0">OK</span> <b style="color:#999">1s</b>

<div style="background:#fff;color:#111;width:29ex">
  🌈 SUMMARY RESULTS 🌈

</div>
<b>Suites:</b>   <span style="color:#0f0">2 passed</span>, 2 of 2 completed
<b>Asserts:</b>  <span style="color:#0f0">3 passed</span>, of 3
<b style="color:#999">Time:     1s</b>
----------------------|----------|----------|----------|----------|-------------------|
File                  |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
----------------------|----------|----------|----------|----------|-------------------|
All files             |    <b style="color:#ff0">55.56</b> |     <b style="color:#f00">37.5</b> |      <b style="color:#0f0">100</b> |    <b style="color:#ff0">55.56</b> |                   |
 my-awesome-module.js |    <b style="color:#ff0">55.56</b> |     <b style="color:#f00">37.5</b> |      <b style="color:#0f0">100</b> |    <b style="color:#ff0">55.56</b> |           <b style="color:#f00">6,7,8,9</b> |
----------------------|----------|----------|----------|----------|-------------------|
</code></pre>

Ouch, only 55% coverage.  That's not very good.  Let's see what lines
are covered:

```bash
$ npm test -- --coverage-report=lcov
```

This runs the tests and opens a [pretty coverage
report](/my-awesome-module/coverage-1/lcov-report/index.html) in a
web browser.  This shows that the second half of our function [isn't being
called](/my-awesome-module/coverage-1/lcov-report/my-awesome-module.js.html).

Ok, add some more tests then:

```js
// test/basic.js
const tap = require('tap')
const mam = require('../my-awesome-module.js')
<commit_msg>docs: make static html links open in a new tab<commit_after>---
title: Getting Started
section: 1
redirect_from:
  - /docs/
  - /docs
  - /basics/
  - /basics
---

# Getting Started

## tap includes out of the box:

`tap` includes out of the box:

1. [A test framework](/docs/api/) for writing tests in Node.js.
2. [A command-line interface](/docs/cli/) for running tests and reporting on their
   success or failure.
3. [Support for test-coverage](/docs/coverage/), including coverage of child
   processes spawned in the process of testing.
4. [Support for parallel tests](/docs/api/parallel-tests/), including running some tests in
   parallel, and others serially.

See [the changelog](/changelog/) for recent updates, or just get started with the basics down below.

[![Build Status](https://travis-ci.org/tapjs/node-tap.svg?branch=master)](https://travis-ci.org/tapjs/node-tap)

## tap basics

This tutorial will teach you just enough to get up and running with tap in your
Node.js programs.

## install tap

Use npm to install tap:

```bash
npm install tap --save-dev
```

The `save-dev` part makes it saved to your package.json's `devDependencies`
list instead of as a regular dependency.

Next, update your package.json so that the test script invokes tap:

```json
{
  "name": "my-awesome-module",
  "version": "1.2.3",
  "devDependencies": {
    "tap": "^13.0.0"
  },

  "scripts": {
    "test": "tap"
  }
}
```

## test files

Create a folder for your tests.  Call the folder `test` so that people
can guess what it's for:

```bash
mkdir test/
```

It's a good practice to break up a big test suite into multiple files.
Each file should cover a feature or concept.  For small Node modules,
often a single test file is enough.

I usually call the first one `test/basic.js`, because it covers the
basic functionality.

By default, when you run `tap` with no arguments, it'll run any files in the
`test` directory, as well as any files than end in `*.spec.js` or `*.test.js`.
If you want to run a specific file, you can also put it on the command line
directly:

```bash
tap test/foo.js
```

## "hello world" test program

The root tap object is a member of tap's `Test` class.  That means it
has all the same properties as child tests.

Here's a very basic test program:

```javascript
// test/hello-world.js
const tap = require('tap')
tap.pass('this is fine')
```

If we run this with node, we'll see the raw TAP output:

```bash
$ node test/hello-world.js
```

```tap
TAP version 13
ok 1 - this is fine
1..1
# time=26.792ms
```

You can always run a tap test program directly to see what it is
doing.  This is especially handy in debugging test failures

That output is "TAP" or "Test Anything Protocol".  It has a long
history in the Perl community, and there are many tools in many
languages that can generate and parse this format.

Node-tap is one of those tools, so let's have it create something
prettier for us.  Because we installed tap as a devDependency, and
added it as a script in package.json, we can run `npm test` to run all
our tests with the `tap` built-in cli.

<pre class="language-text"><code class="language-text">
$ npm test

> my-awesome-module@1.2.3 test /Users/isaacs/dev/js/tap/docs/static/my-awesome-module
> tap

<span style="background:#0f0;color:#000;padding-top:2px"> PASS </span> test/hello-world.js <b style="color:#fff">1</b> <span style="color:#0f0">OK</span> <b style="color:#999">1s</b>

<div style="background:#fff;color:#111;width:29ex">
  🌈 SUMMARY RESULTS 🌈

</div>
<b>Suites:</b>   <span style="color:#0f0">1 passed</span>, 1 of 1 completed
<b>Asserts:</b>  <span style="color:#0f0">1 passed</span>, of 1
<b style="color:#999">Time:     1s</b>
----------|----------|----------|----------|----------|-------------------|
File      |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
----------|----------|----------|----------|----------|-------------------|
All files |        0 |        0 |        0 |        0 |                   |
----------|----------|----------|----------|----------|-------------------|
</code></pre>

## coverage

Test coverage makes it a lot easier to know that we're testing what we
think we're testing.

So, let's create a module to test.  Let's say that we want a function
that returns 'even' if the number is even, or 'odd' if it's odd,
unless it's greater than 100, in which case it should return 'big',
and if it's less than 0, it should return 'negative'.

```javascript
// my-awesome-module.js
module.exports = x => {
  if (x % 2 === 0) {
    return 'even'
  } else if (x % 2 === 1) {
    return 'odd'
  } else if (x > 100) {
    return 'big'
  } else if (x < 0) {
    return 'negative'
  }
}
```

Probably no bugs!

Now, we can create a test file that pulls it in and verifies the
result:

```javascript
// test/basic.js
const tap = require('tap')
const mam = require('../my-awesome-module.js')

// Always call as (found, wanted) by convention
tap.equal(mam(1), 'odd')
tap.equal(mam(2), 'even')
```

Looks good to me!

<pre class="language-text"><code class="language-text">
$ npm test

> my-awesome-module@1.2.3 test /Users/isaacs/dev/js/tap/docs/static/my-awesome-module
> tap

<span style="background:#0f0;color:#000;padding-top:2px"> PASS </span> test/basic.js <b style="color:#fff">2</b> <span style="color:#0f0">OK</span> <b style="color:#999">1s</b>
<span style="background:#0f0;color:#000;padding-top:2px"> PASS </span> test/hello-world.js <b style="color:#fff">1</b> <span style="color:#0f0">OK</span> <b style="color:#999">1s</b>

<div style="background:#fff;color:#111;width:29ex">
  🌈 SUMMARY RESULTS 🌈

</div>
<b>Suites:</b>   <span style="color:#0f0">2 passed</span>, 2 of 2 completed
<b>Asserts:</b>  <span style="color:#0f0">3 passed</span>, of 3
<b style="color:#999">Time:     1s</b>
----------------------|----------|----------|----------|----------|-------------------|
File                  |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
----------------------|----------|----------|----------|----------|-------------------|
All files             |    <b style="color:#ff0">55.56</b> |     <b style="color:#f00">37.5</b> |      <b style="color:#0f0">100</b> |    <b style="color:#ff0">55.56</b> |                   |
 my-awesome-module.js |    <b style="color:#ff0">55.56</b> |     <b style="color:#f00">37.5</b> |      <b style="color:#0f0">100</b> |    <b style="color:#ff0">55.56</b> |           <b style="color:#f00">6,7,8,9</b> |
----------------------|----------|----------|----------|----------|-------------------|
</code></pre>

Ouch, only 55% coverage.  That's not very good.  Let's see what lines
are covered:

```bash
$ npm test -- --coverage-report=lcov
```

This runs the tests and opens a <a target="my-awesome-module-report"
href="/my-awesome-module/coverage-1/lcov-report/index.html">pretty coverage
report</a> in a web browser.  This shows that the second half of our
function <a target="my-awesome-module-report"
href="/my-awesome-module/coverage-1/lcov-report/my-awesome-module.js.html">isn't
being called</a>.

Ok, add some more tests then:

```js
// test/basic.js
const tap = require('tap')
const mam = require('../my-awesome-module.js')

{'fraction_non_alphanumeric': 0.2102499474900231, 'fraction_numerical': 0.023944549464398234, 'mean_word_length': 2.7275574112734864, 'pattern_counts': {'":': 12, '<': 157, '<?xml version=': 0, '>': 167, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5003515', 'n_tokens_mistral': 5089, 'n_tokens_neox': 4620, 'n_words': 1589}