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.


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


Jekyll is a Ruby Gem, which requires Ruby 2.5.0 or higher installed (ruby -v) and the RubyGems package manager installed (gen -v). Note that GCC and Make are not required for previewing test specs.


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#

It is recommended to set up Jekyll in the same folder as your test specs (i.e. cd specs). There are 5 files required to be added to your repo under the specs folder:

โ””โ”€ _config.yml
โ””โ”€ .gitignore
โ””โ”€ Gemfile
โ””โ”€ Gemfile.lock
  1. Jekyll requires a configuration file:
title: Spec Preview
layout: "default"
theme: just-the-docs
remote_theme: pmarsceill/just-the-docs
  1. The following Gemfile file is required:
source ""
gem "jekyll", "4.2.0"
gem "just-the-docs"
# Performance-booster for watching directories on Windows
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