Links

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
Testing a track can only be done from Instruqt CLI. Pull a track to your machine first, if needed.
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. 1.
    Setting up challenge. ↳ Instruqt runs the setup script.
  2. 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. 3.
    Running solve. ↳ Instruqt runs the solve script that mimics the learner and solves the challenge.
  4. 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 and solve) have been implemented correctly.
The test stops when one of the steps fails or when all steps have been completed successfully.

Test on-demand or automatically

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.

Test a track

💻 Instruqt CLI
  1. 1.
    Open a terminal and move into your track directory:
    cd DIRECTORY_NAME
    ⇨ Replace DIRECTORY_NAME with your track directory.
  2. 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 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
    TEAM, TRACK_SLUG, and YOUR_CHALLENGE_NAME_x will be your team, track slug, and challenge names. And your track and challenge IDs will also differ.

Skip the checking steps

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

Keep your track running after testing

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

Test a track automatically from CI/CD systems

Set authentication

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.

Use the Instruqt Docker Container 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.
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.