Skip to content

Commit

Permalink
CLI: Move "Getting started in Node.js" from Intro to CLI page
Browse files Browse the repository at this point in the history
Matching what we do with the browser page.
  • Loading branch information
Krinkle committed Jun 29, 2024
1 parent 75527da commit aaa6e2f
Show file tree
Hide file tree
Showing 4 changed files with 96 additions and 85 deletions.
2 changes: 1 addition & 1 deletion docs/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Open your HTML file in a browser to find a detailed report. Live example ([open

<iframe loading="lazy" title="Example test suite running in the browser" src="/resources/example-add.html" style="height: 380px;"></iframe>

Congrats! You just executed your first QUnit test!
**Congrats!** You just executed your first QUnit test!

## Fixture

Expand Down
100 changes: 90 additions & 10 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
layout: page
title: Command-line Interface
excerpt: Test JavaScript code in Node.js with the QUnit CLI.
redirect_from:
- "/node/"
amethyst:
Expand All @@ -9,10 +10,86 @@ amethyst:

<p class="lead" markdown="1">

How to use the QUnit CLI (command-line interface), after [installing it from npm](./intro.md#in-nodejs).
This tutorial gets you up-and-running with QUnit in Node.js.

</p>

_For browser automations from the command-line, refer to [Browser automation](./browser.md#integrations) instead._

## Getting started

Getting started with QUnit to test your Node.js projects is quick and easy.<br>
First, install the [qunit](https://www.npmjs.com/package/qunit) package from `npm`:

```bash
npm install --save-dev qunit

# Or, if using Yarn:
yarn add --dev qunit
```

Let's create an example program that we can test! We'll start with a function that adds two numbers. Create a file `add.js` with the following contents:

```js
function add (a, b) {
return a + b;
}

module.exports = add;
```

Now, let's start writing tests!<br>
Create a file in a test directory, for example `test/add.js`, and write the following:

```js
const add = require('../add.js');

QUnit.module('add');

QUnit.test('two numbers', (assert) => {
assert.equal(add(1, 2), 3);
});
```

This defines a test suite for the "add" feature, with a single test case that verifies the result of adding two numbers together.

You can now run your first test. It is recommended that you run the `qunit` command via npm test, which will automatically find the `qunit` program in your local `node_modules` folder. That's where npm downloads the dependencies. In your `package.json` file, specify it like so:

```json
{
"scripts": {
"test": "qunit"
}
}
```

Then run:

```bash
npm test
```

**Congrats!** You just wrote and executed your first QUnit test!

```bash
TAP version 13
ok 1 add > two numbers
1..1
# pass 1
# skip 0
# todo 0
# fail 0
```

Check out the [API documentation](./api/index.md) to learn more. For example, use [`QUnit.module()`](./api/QUnit/module.md) to organize test, or make other kinds of comparisons via the [assertion methods](./api/assert/index.md).

## Efficient development

As your project grows, you may reach a point where the complete test suite takes more than a second to run. QUnit provides several ways to maintain a fast feedback cycle on the command-line.

* Use [`--watch`](#--watch) to automatically re-run tests after making changes to your files.
* When building out a larger feature, use [`--filter`](#--filter) or `--module` to run only a subset of tests.

## QUnit CLI options

```
Expand Down Expand Up @@ -91,15 +168,6 @@ Automatically re-run your tests after file changes in the current directory.

In watch mode, QUnit will run your tests once initially, and then keep watch mode open to re-run tests after files changed anywhere in or under the current directory. This includes adding or removing files.

## Efficient development

_For browser automations from the command-line, refer to [Browser automation](./browser.md#integrations) instead._

As your project grows, you may reach a point where the complete test suite takes more than a second to run. QUnit provides several ways to maintain a fast feedback cycle on the command-line.

* Use `--watch` to automatically re-run tests after making changes to your files.
* When building out a larger feature, use `--filter` or `--module` to run only a subset of tests.

## Node.js CLI options

The QUnit CLI uses Node.js. You can pass [Node.js CLI](https://nodejs.org/api/cli.html) options via the [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#cli_node_options_options) environment variable. For example, to use `--enable-source-maps` or `--inspect`, invoke QUnit as follows:
Expand Down Expand Up @@ -127,3 +195,15 @@ Generate code coverage reports with [nyc](https://istanbul.js.org/):
See [/test/integration/nyc/](https://github.com/qunitjs/qunit/tree/main/test/integration/nyc) in the QUnit repo for a minimal example.

For a more elaborate example showcasing a unified test coverage report for tests in both Node.js and a headless browser, see [Krinkle/example-node-and-browser-qunit](https://github.com/Krinkle/example-node-and-browser-qunit-ci/).

## Node.js support policy

QUnit follows the <a href="https://github.com/nodejs/LTS" target="_blank">Node.js Long-term Support (LTS) schedule</a> and provides support for at least the Current, Active LTS, and Maintenance LTS releases.

## npm Package name

Since QUnit 2.4.1, the official npm package is [qunit](https://www.npmjs.com/package/qunit).

Earlier versions of QUnit were published to npm under the name "qunit**js**" instead of "qunit". To download these earlier versions refer to the [qunitjs](https://www.npmjs.com/package/qunitjs) package.

The 0.x and 1.x versions of the "qunit" package held an alternative CLI, now known as [node-qunit](https://github.com/qunitjs/node-qunit).
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ home_secondary_btn:
<section class="grid grid--small home-highlights">
<div>
<h2>Easy</h2>
<p>Easy, zero configuration setup for any Node.js project and minimal configuration for Browser-based projects.</p>
<p>Zero configuration and setup for any Node.js project, and minimal setup for Browser-based projects.</p>
</div>

<div>
Expand Down
77 changes: 4 additions & 73 deletions docs/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,86 +9,17 @@ redirect_from:

<p class="lead" markdown="1">

This tutorial gets you up-and-running with QUnit in Node.js or [in the browser](./browser.md).
Up-and-running with QUnit [in Node.js](./cli.md) or [in the browser](./browser.md).

</p>

QUnit has no dependencies and supports Node.js, SpiderMonkey, and all [major browsers](./browser.md#browser-support).

## In Node.js

Getting started with QUnit for Node.js projects is quick and easy. First, install the [qunit](https://www.npmjs.com/package/qunit) package using `npm`:

```bash
npm install --save-dev qunit

# Or, if using Yarn:
yarn add --dev qunit
```

Let's create an example program that we can test! We'll start with a function that adds two numbers. Create a file `add.js` with the following contents:

```js
function add (a, b) {
return a + b;
}

module.exports = add;
```

Now, let's start writing tests! Create a file in a test directory, for example `test/add.js`, and write the following:

```js
const add = require('../add.js');

QUnit.module('add');

QUnit.test('two numbers', (assert) => {
assert.equal(add(1, 2), 3);
});
```

This defines a test suite for the "add" feature, with a single test case that verifies the result of adding two numbers together. Refer to the [`QUnit.test()` page](./api/QUnit/test.md) in our API Documentation for how to organise tests and make other assertions.

You can now run your first test through the [QUnit CLI](./cli.md). It is recommended that you run the `qunit` command via an npm script, which will automatically find the `qunit` program in your local `node_modules` folder, which is where npm keeps the dependencies you download. In your `package.json` file, specify it like so:

```json
{
"scripts": {
"test": "qunit"
}
}
```

Then run:

```bash
npm test
```

Congrats! You just wrote and executed your first QUnit test!

```bash
TAP version 13
ok 1 add > two numbers
1..1
# pass 1
# skip 0
# todo 0
# fail 0
```

Check out the [API documentation](./api/index.md) to learn more about the QUnit APIs for organising tests and making assertions. See [Command-line Interface](./cli.md) for what the `qunit` command can do.

### Support policy

QUnit follows the <a href="https://github.com/nodejs/LTS" target="_blank">Node.js Long-term Support (LTS) schedule</a> and provides support for Current, Active LTS, and Maintenance LTS releases.

### Package name prior to 2.4.1
[Getting Started in Node.js](./cli.md)

Prior to QUnit 2.4.1, the npm package was published under the name "qunit**js**" instead of "qunit". To install earlier versions of QUnit for Node, check out [qunitjs](https://www.npmjs.com/package/qunitjs).
## In the browser

The 0.x and 1.x versions of the "qunit" package on npm holds an alternative CLI that is now published as [node-qunit](https://github.com/qunitjs/node-qunit).
[Getting Started in the browser](./browser.md)

---

Expand Down

0 comments on commit aaa6e2f

Please sign in to comment.