Verified Steps in Labs

Ensuring that users have successfully completed certain actions before the proceed can be a useful technique to ensure that are paying attention and they won’t hit problems later on in the scenario.

Verification Script

If you include verification scripts for the step(s) in your lab, when the user clicks Continue, a script is run against the environment. This provides some of the functionality of a challenge to your labs.

NOTE: If you are trying to show/hide content (for example, asking a learner to think about a problem prior to seeing the solution) without the need for explicit verification, please use the show/hide markup instead.

For the user to be allowed to proceed, the script should output the text “done.” For example, the following verify script checks to make sure the user has run git init before they can proceed:

#!/bin/bash

[ -d /home/scrapbook/tutorial/.git ] && echo "done"

To include the verification to a step, you add it to the step object inside the "steps" array in index.json. For example:

"details": {
    "steps": [
        {
            "title": "Verified Step Example",
            "text": "step1.md",
            "verify": "step1-verify.sh"
        }
    ]
}

Answsers

To provide users with more information or context, an “answer” section can be provided inside the step object in index.json:

"details": {
    "steps": [
        {
            "title": "Show Answers",
            "text": "step2.md",
            "verify": "step2-verify.sh",
            "answer": "step2-answer.md"
        }
    ]
}

This creates the “Show Solution” option inside the lab. Here is an example from the learning platform:

Solutions

To aid in testing of labs with verified steps, add a solution script for each step that has a verification script. The solution script should adhere to the same protocol as the verification script: it should output “done” when the solution is successfully applied.

The solution script will not be offered to learners; it will only be available to authors and editorial staff.

The solution script will be invoked by Instruction-Guided Tests when they are run. This provides test coverage for executable actions in your instructions as well as your verification script. (Tests will fail if verification passes before the solution is applied.)

"details": {
    "steps": [
        {
            "title": "Verified Step Example",
            "text": "step1.md",
            "verify": "step1-verify.sh",
            "solution": "step1-solution.sh"
        }
    ]
}

For example, if the verify script checks to make sure the user has run git init, then the solution should do just that:

#!/bin/bash

set -e

cd /home/scrapbook/tutorial/.git
git init
echo done

Solutions may be provided with or without an answer.

If no solution is provided, an author or editorial staff member can still bypass verification without applying any solution. This allows access to the instructions of later steps for copy editing purposes, but it does not allow testing of any commands in the instructions. For this reason, we encourage you to provide solutions for all verified steps that you create.