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.

tip

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.

important

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.

Setup

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

Prerequisites

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

important

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.

specs
└─ _config.yml
└─ .gitignore
└─ Gemfile
└─ Gemfile.lock
└─ index.md
..
  1. Jekyll requires a configuration file:
/specs/_config.yml
title: Spec Preview
defaults:
-
values:
layout: "default"
theme: just-the-docs
  1. The following Gemfile file is required:
/specs/Gemfile
source "https://rubygems.org"

gem "jekyll", "4.2.0" # 4.2.1+ does not work in Codespaces with the "just-the-docs" theme
gem "just-the-docs"

gem "webrick", "~> 1.7" # required for ruby 3.0+
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
  1. A simple index markdown file is required:
/specs/index.md
---
layout: home
---

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

Install

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

Run

To Run Jekyll use the following:

cd specs
bundle exec jekyll serve 

Goto: http://127.0.0.1:4000/

Specs

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

Front Matter

Add the following variable:

title: Spec Name

Assignment

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.

Example

The following is a template example:

specs/hello.md
---
testspace:
title: Hello
---

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

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

## My First Case

- Do this
- Do that