jest-hugo

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.100.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.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.