Test a track
Just to be sure.
This guide explains how to test a track to ensure your content is free from errors and issues that could cause a bad experience for learners.
Instruqt supports automated testing of your tracks via the
instruqt track test
command. 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. With this, you can ensure your track is free from errors and issues that could cause a bad experience for learners.Only from Instruqt CLI
Solve script needed
Because Instruqt executes the challenge lifecycle scripts to test a track, a solve script is needed to test a track successfully. A solve script executes a challenge automatically.
When you run
instruqt track test
, Instruqt executes the following steps on each challenge:- 1.Setting up challenge. ↳ Instruqt runs the setup script.
- 2.Running check, expecting failure. ↳ Instruqt runs the check script and expects this script to fail because the solve script has not been run yet.
- 3.Running solve. ↳ Instruqt runs the solve script that mimics the learner and solves the challenge.
- 4.Running check, expecting success. ↳ Instruqt reruns the check script and expects this script to succeed now because the solve script has been run.
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
andsolve
) have been implemented correctly.
The test stops when one of the steps fails or when all steps have been completed successfully.
You can run your tests on-demand from Instruqt CLI, but you can also integrate your tests into a CI/CD system where your tests run automatically.
💻 Instruqt CLI
- 1.Open a terminal and move into your track directory:cd DIRECTORY_NAME⇨ Replace
DIRECTORY_NAME
with your track directory. - 2.Enter the following command:instruqt track test↳ Instruqt CLI shows output like this:==> 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 OKRunning check, expecting failure OKRunning solve OKRunning check, expecting success OK==> Testing challenge [2/2] 'YOUR_CHALLENGE_NAME_2' (ID: pjdxmwz493v8)Setting up challenge OKRunning check, expecting failure OKRunning solve OKRunning check, expecting success OK⇨
TEAM
,TRACK_SLUG
, andYOUR_CHALLENGE_NAME_x
will be your team, track slug, and challenge names. And your track and challenge IDs will also differ.
Use the
--skip-fail-check
flag in the instruqt track test
command to skip the first check attempt and go straight to the solve script. Furthermore, the checking steps will fail if you have not implemented check scripts for your track. To avoid this failure, you can use the same --skip-fail-check
flag in the instruqt track test
command.💻 Instruqt CLI
instruqt track test --skip-fail-check
When the test has finished, it will automatically stop the track and mark it for cleanup. 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
To run tests from a CI/CD system like Jenkins, you must authenticate the tests from such systems with an Instruqt API token. To do this, first, create an API token. And second, create an environment variable
INSTRUQT_TOKEN
with the value of your API token in your CI/CD system.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.
Check! You guarantee the quality of your tracks, and your learners will thank you for that. But you can go even further and maintain a developer workflow to ensure error-free tracks without the risk of disrupting production tracks.
Last modified 1mo ago