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.

info

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.

info

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
search_enabled: false
  1. The following Gemfile file is required:
/specs/Gemfile
source "https://rubygems.org"

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:
/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