Skip to main content

Desktop Preview

The Testspace Spec model is compatible with the GitHub Jekyll model, where a separate parsing and static HTML generation step occurs. As a result of this approach, it is easy to leverage Jekyll for local Spec development and previewing.


Use Jekyll on your desktop for local test spec development and previewing.

We are recommending using the Jekyll documentation theme called Just The Docs for reviewing specs. Note that other Themes are also available, or you can develop your own.


Testspace follows GitHub Markdown, not the Jekyll version of markdown. Sometimes they do not match. When having problems with rendering, always check the spec for proper displaying using the repo.


To leverage Jekyll on the desktop, a few one-time steps are required.


Jekyll is a Ruby Gem, which requires Ruby and RubyGems.


For more details on installing Jekyll refer here.

Install Jekyll

The first step is to install the Jekyll gem:

gem install jekyll bundler

Required Files

Setup Jekyll in the same folder as your test specs (i.e. cd specs). There are 5 files required to be added to your repo.

The following sections assume the use of the specs folder.

└─ _config.yml
└─ .gitignore
└─ Gemfile
└─ Gemfile.lock
  1. Jekyll requires a configuration file:
title: Spec Preview
layout: "default"
theme: just-the-docs
search_enabled: false
  1. The following Gemfile file is required:
source ""

gem 'jekyll', '~> 4.3', '>= 4.3.3'
gem 'just-the-docs', '~> 0.8.0'

gem 'webrick', '1.8.1' # required for ruby 3.0+
gem 'wdm', '0.1.1', :platforms => [:mingw, :x64_mingw, :mswin]
  1. A simple index markdown file is required:
layout: home

This is were the Manual Test `Specs` live.
  1. A .gitignore file should be added, ignoring the local Jekyll generated file:
# Jekyll local building artifacts
  1. Note that the Gemfile.lock will be automatically generated on the following install step.


Once the files have been added, or if the repo has been cloned/forked, it is required run the bundler to install dependencies based on the Gemfile:

cd specs
bundle install


To Run Jekyll use the following:

cd specs
bundle exec jekyll serve



For a Spec to be listed using Jekyll, the following additions are required.

Front Matter

Add the following variable:

title: Spec Name


The spec object requires assignment to the page object. Add this 1-line statement after the front matter header block:

{% if page %} {% assign spec = page %} {% endif %}

Spec Name

To synchronize the title name and spec name, it is recommended to use the following global variable for the spec name:

# {{ spec.title }}
Spec optional description.


The following is a template example:

title: Hello

{% if page %} {% assign spec = page %} {% endif %}

# {{ spec.title }}
Spec description text .. blah blah

## My First Case

- Do this
- Do that