jest-hugo


Overview

jest-hugo allows you to test your Hugo theme.

Tests are written in a _tests_ directory in files having the _.md_ extension.
Jest is used for testing. The Jest watch mode is also supported (no need for Hugo in watch mode).

Requirements

1. Jest 24+
2. NodeJS 8+
3. Hugo >= v0.100.0

Usage

$3

Add jest-hugo and jest packages to your theme repo: npm install --save jest jest-hugo

$3

#### Guidelines

- Create a tests subdirectory with .md files under it
- Each test must be written in Markdown
- The Hugo output is generated under /.output and is auto-cleaned before each run
- To exclude a Markdown file from testing, use _.ignore.md_ as file extension (instead of _.md_)
- Usage with test reporters is also supported. For that, refer to the demo subdirectory.

#### Nominal Cases ✔️

Write each test case enclosed in a tag where name can be any descriptive name representing the test. Example:

``

{{% myshortcode %}}
...
{{% /myshortcode %}}

`

When running the tests, a Jest __snapshots__ subdirectory will be created at the same level as your test file.

#### Error Cases ❌

This project allows asserting errors from errorf. For that, use the expect keyword the following way:

`

{{< expect error="Invalid type!" >}}
{{% myshortcode type="invalid" %}}
...
{{% /myshortcode %}}

`

When running the tests, _ERROR YYYY/MM/DD HH:MM:SS shortcodes\\myshortcode.md: Invalid type!_ will be expected to be found in the Hugo output.

$3

1. Run tests using npm run jest
2. Update Jest snapshots with jest -u
3. For watch mode, use jest --watchAll which will rerun tests whenever there is an update.

Configuration

$3

You can provide your own Hugo config by creating a jest-hugo.config.json file at the root of your project.

$3

| Variable | Description | Default |
| ---------------------- | -------------------------- | ------- |
| JEST_HUGO_TEST_DIR | Name of the test directory | "tests" |
| JEST_HUGO_EXECUTABLE | Name of the Hugo command | "hugo" |
| JEST_HUGO_DEBUG | Output additional logs | false |

Demo

1. Checkout this repo
2. Run npm install or yarn install
3. Go to the demo subdirectory
4. Run npm install or yarn install
5. Run tests using npm run jest or yarn jest

The demo was tested with Hugo v0.100.0 and the latest version.

Known Limitations

- This project requires to enable unsafe: true for the Goldmark renderer. See: markup.goldmark.renderer.
- Ensure that each test file has a front matter (an empty one works too). See callout.md for example.
- One single log message is created for multiple calls to errorf with the exact same string. This means a single test file can't output multiple times the same error, and test cases expecting an exact same error message must be defined in their own _.md_ file (see demo/tests/shortcodes` subdirectory) (see also: #20).

Feel free to give feedback.