README

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

Jest 24+
NodeJS 8+
Hugo >= v0.62.0

Usage

Adding Dependencies

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

Writing Tests

Guidelines

Create a tests subdirectory with .md files under it
Each test must be written in Markdown
The Hugo output is generated under <test dir>/.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 <test name="test name"> tag where name can be any descriptive name representing the test. Example:

<test name="should render successfully">
  {{% myshortcode %}}
  ...
  {{% /myshortcode %}}
</test>

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:

<test name="should throw an error when invalid type is provided">
  {{< expect error="Invalid type!" >}}
  {{% myshortcode type="invalid" %}}
  ...
  {{% /myshortcode %}}
</test>

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.

Running Tests

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

Configuration

Hugo Configuration

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

Environment Variables

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

Checkout this repo
Run npm install or yarn install
Go to the demo subdirectory
Run npm install or yarn install
Run tests using npm run jest or yarn jest

The demo was tested with Hugo v0.62.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.
This project leverages the warnf template func introduced with Hugo v0.62.0. For that reason, versions of Hugo before 0.62.0 aren't supported anymore.
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.

Usage no npm install needed!