https://github.com/manixate/jest-hugo
Run tests for your hugo content using Jest
https://github.com/manixate/jest-hugo
hugo jest testing
Last synced: 8 months ago
JSON representation
Run tests for your hugo content using Jest
- Host: GitHub
- URL: https://github.com/manixate/jest-hugo
- Owner: manixate
- License: mit
- Created: 2019-07-26T12:48:31.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2023-03-11T13:13:58.000Z (over 3 years ago)
- Last Synced: 2024-09-29T05:41:16.389Z (over 1 year ago)
- Topics: hugo, jest, testing
- Language: JavaScript
- Homepage:
- Size: 579 KB
- Stars: 5
- Watchers: 8
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# jest-hugo
[](https://www.npmjs.com/package/jest-hugo)
[](https://github.com/manixate/jest-hugo/blob/master/LICENSE)
[](https://github.com/manixate/jest-hugo/actions/workflows/demo.yml)
[](https://github.com/manixate/jest-hugo/actions/workflows/prettier.yml)
## Overview
`jest-hugo` allows you to test your [Hugo](https://github.com/gohugoio/hugo) theme.
Tests are written in a _tests_ directory in files having the _.md_ extension.
[Jest](https://jestjs.io/) 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](https://github.com/gohugoio/hugo/releases/tag/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 `/.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`](./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`](https://gohugo.io/functions/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.
### Running Tests
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
### 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
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](https://github.com/gohugoio/hugo/releases/tag/v0.100.0) and the [latest](https://github.com/gohugoio/hugo/releases/latest) version.
## Known Limitations
- This project requires to enable `unsafe: true` for the Goldmark renderer. See: [`markup.goldmark.renderer`](https://gohugo.io/getting-started/configuration-markup).
- Ensure that each test file has a front matter (an empty one works too). See [`callout.md`](./demo/tests/shortcodes/callout.md?plain=1) for example.
- One single log message is created for multiple calls to [`errorf`](https://gohugo.io/functions/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`](./demo/tests/shortcodes) subdirectory) (see also: [#20](https://github.com/manixate/jest-hugo/issues/20)).
Feel free to give feedback.