Test tracks

Test track sandboxes by running simulated plays

Before you begin

This guide explains how to test a track to ensure your content is free from errors. You need the following to test tracks:

• The Instruqt CLI

• Check and solve scripts in your challenges

Background

The instruqt track test command simulates a user starting and completing a track. When you run this command, Instruqt starts a new instance of your track and simulates a learner going through the track by executing all challenge lifecycle scripts.

In the test, Instruqt deploys an instance of the track's sandbox (and runs the track setup scripts) and performs the following steps for each challenge:

1. Run the challenge setup script

2. Run check script, expecting failure.

3. Run solve script, to mimic what the user would do.

4. Run check script again, expecting success.

By running these steps, you achieve the following:

• Mimic the learner's behavior.

• Validate that the track starts properly.

• Validate that the challenge life cycle scripts (setup, check and solve) have been implemented correctly.

The test stops when one of the steps fails or when all steps have been completed successfully.

Test a track

Tracks can only be tested using the Instruqt CLI.

💻 Instruqt CLI

1. In a track's directory, run the following command:

   instruqt track test

   ↳ Example output:

   ==> Finding track by slug: TEAM/TRACK_SLUG
   ==> Testing track 'TEAM/TRACK_SLUG' (ID: jum7k2jboetj)
       Creating environment ....... OK
   
   ==> Testing challenge [1/2] 'YOUR_CHALLENGE_NAME_1' (ID: pjdxmwz493v7)
       Setting up challenge              OK
       Running check, expecting failure  OK
       Running solve                     OK
       Running check, expecting success  OK
       
   ==> Testing challenge [2/2] 'YOUR_CHALLENGE_NAME_2' (ID: pjdxmwz493v8)
       Setting up challenge              OK
       Running check, expecting failure  OK
       Running solve                     OK
       Running check, expecting success  OK

Skip the checking steps

Add the --skip-fail-check flag to the instruqt track test command to skip the first check attempt and go straight to the solve script.

💻 Instruqt CLI

instruqt track test --skip-fail-check

The "Running check" steps will fail if you do not have check scripts present in your track.

Keep tracks running after testing

When the test has finished, it will automatically stop the track and delete the sandbox. If you would like to keep it running afterward, add the --keep-running flag to the instruqt track test command. This is useful when you debug a script issue and want to inspect the environment after the test has finished. If you are running the test with your credentials, you can go to play.instruqt.com and continue with the track where the test finished.

💻 Instruqt CLI

instruqt track test --keep-running

Test in CI/CD pipelines

Set authentication

To run tests from a CI/CD system like GitHub actions, you must authenticate with an Instruqt API token. To do this, create an API token. Once you have your API token, create an environment variable named INSTRUQT_TOKEN with the token value in your CI/CD system.

Docker Image

Many CI/CD systems support running commands on containers as part of the build/test process. Instruqt provides a Docker Container Image with the current version of the Instruqt CLI pre-installed. Use this image in your CI/CD test pipelines to access the Instruqt CLI easily.