# Test tracks

## 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 ](https://docs.instruqt.com/reference/cli/commands)
* [Check and solve scripts in your challenges](https://docs.instruqt.com/sandboxes/lifecycle-scripts/add-a-script-to-check-challenge-execution)

## 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.

{% tabs %}
{% tab title="💻 Instruqt CLI" %}

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

   ```xml
   instruqt track test
   ```

   ↳ Example output:

   ```xml
   ==> 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
   ```

{% endtab %}
{% endtabs %}

### 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. 

{% tabs %}
{% tab title="💻 Instruqt CLI" %}

```
instruqt track test --skip-fail-check
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The "Running check" steps will fail if you do not have check scripts present in your track.
{% endhint %}

### 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](https://play.instruqt.com) and continue with the track where the test finished.

{% tabs %}
{% tab title="💻 Instruqt CLI" %}

```
instruqt track test --keep-running
```

{% endtab %}
{% endtabs %}

## 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](https://docs.instruqt.com/settings/platform/api#api-authorization). 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](https://hub.docker.com/r/instruqt/cli) in your CI/CD test pipelines to access the Instruqt CLI easily.