puppetlabs / quest

Quest-driven learning with RSpec

Quest

Quest-driven learning with RSpec and Serverspec.

What it is

The quest gem provides a learner with live feedback as a learner progresses through a series of configuration management tasks defined by RSpec tests. It was designed to support the Puppet Quest Guide content on the Puppet Learning VM, but can be used for any project with a compatible format.

Installation

From source:

git clone https://github.com/puppetlabs/quest.git
cd quest
gem build quest.gemspec
gem install quest<VERSION>.gem

Setup

This gem was designed to support the Puppet Quest Guide, and works with any set of tests and metadata following the same pattern.

Any project you wish to use with this tool must contain a directory with the following contents:

An index.json file consisting with available quest names, the list of files to watch for each quest and an optional setup command for that quest. These setup commands will be run with the directory of your tests as the current working directory when a user begins the quest.

{
  "welcome": {
    "setup_command": "puppet apply ./manifests/welcome.pp"
  }
}

A series of *_spec.rb files corresponding the the quest names specified in the index.json. These files must contain valid Rspec tests that correspond to the tasks in that quest. For example, my_first_quest_spec.rb might contain the following. (Note the callous abuse of the RSpec format to coerce its output into something appropriate to the quest tool interface.)

describe "Task 1: do
  it 'create a user named test' do
    file('/etc/passwd').should contain "test"
  end
end
describe "Task 2: do
 ...
end

A spec_helper file with any required libraries, helper functions, or variables needed by the tests.

require 'serverspec'
require 'pathname'

PROD_PATH = '/etc/puppetlabs/code/environments/production'
MODULE_PATH = PROD_PATH + "modules/"

Use

The questctl command is used to start the quest service. Run it from the task directory, or use the --task_dir flag.

/usr/local/bin/questctl start --task_dir /usr/src/puppet-quest-guide/tests

This works best when the service is managed by an init system, for example:

# /etc/systemd/system/quest.service
[Unit]
Description=Quest tool service

[Service]
ExecStart=/usr/local/bin/questctl start --task_dir /usr/src/puppet-quest-guide/tests

[Install]
WantedBy=multi-user.target

How it works

The quest service runs a set of RSpec tests for the current test in a loop, updating the quest status each time the test completes. The service provides api endpoints on port 4567 that allow access to the RSpec output and a POST endpoint to change the current quest.

The quest command is a wrapper for these API endpoints.

quest's Issues

Fix questctl restart

The questclt restart command doesn't work correctly, as the start command requires a quest directory to be specified.

The quest and questctl tools should behave better when run outside the quest directory.

The quest tool should not need to be run from a quest directory. The questctl tool should be able to take a quest directory as an argument.

Implement automated quest testing

Implement a test function to run through the automated solutions for quests.

Improve setup documentation

How do you prepare a system to use this tool? What are the prerequisites?

Something like:

1. Install OS
2. Install ruby, ruby-dev, git and rmagick
   Install ruby gem fileutils
3. Grab the git repo of Quest
4. Install (automated file copies for tmux config and a demo quest)
5. Generate a splash page for the VM so when it’s spooled up it tells the user to go to an IP address and port via the browser to view the quest.
6. User profile should start tmux
7. Play

Implement an update function

Implement an update function to grab a new version of quest content. Should be able to specify a version or get the latest. Should come with warnings about disrupting quest progress based on semantic versioning.

Rework watch directory configuration

Currently the watch directories for each quest are kept in separate config.json files in the directory for each quest. There should be a way to set a watch directory to apply globally, so these don't need to be redundantly specified for each. It may best to also include specific information for each quest in a single configuration file to make editing easier.

No index.html page is generated

No index.html page is generated with the questctl build command.

rspec doesn't reset correctly between runs

rspec doesn't reset correctly between runs, resulting in failed tests with the following exception:

  "exception": {
    "class": "RSpec::Core::MultipleExceptionError",
    "message": "undefined method `teardown_mocks_for_rspec' for nil:NilClass\n\nundefined local variable or method `__init_memoized' for nil:NilClass",
    "backtrace": null
  }

Add proper colorization to output for tmux

tmux input doesn't take the same string colorization syntax as the terminal. If we want colorization in tmux, we may have to split the output into several components that can each be colorized within the tmux.conf