Testing & Validation

Before learners start your lab, use the Instruqt CLI to format and validate the lab configuration locally, then use platform playtesting and lab logs to catch runtime problems. This page covers the CLI commands for that workflow.

The lab command group may not appear in root instruqt --help, but the subcommands work when you invoke them as instruqt lab ….

Prerequisites

The Instruqt CLI installed
A local lab directory (for example from project setup with instruqt lab init)
Authentication (instruqt auth login or INSTRUQT_TOKEN) only if you use instruqt lab logs

Format lab configuration

instruqt lab format rewrites HCL so layout and spacing are consistent. It does not check resource references, lab structure, or other semantic rules.

Accepts one HCL file or a directory path
Defaults to the current directory (.) when you omit the path
When given a directory, walks nested folders and rewrites every *.hcl file
Alias: fmt

From your lab directory:

instruqt lab format

Format a single file or another path:

instruqt lab format main.hcl
instruqt lab format path/to/lab
# alias
instruqt lab fmt

Successful runs print OK. Files that needed changes are listed as they are rewritten:

instruqt lab format

==> Formatting lab...
    Formatting main.hcl
    OK

Unparseable HCL causes the command to fail with Error formatting lab. Treat that as a syntax signal only—still run validate for semantic checks.

Validate lab configuration

instruqt lab validate checks the local lab config. It does not start a lab, deploy to the platform, or run learner task scripts.

Optional path argument; defaults to .
No authentication required
Works on a single .hcl file or a directory of top-level .hcl files (directory parse is not recursive into subfolders)

instruqt lab validate
instruqt lab validate path/to/lab

What validation checks

Validation parses your HCL, processes the resource graph, and runs resource-level checks. Hard failures include:

HCL parse or configuration processing errors
Resource validation failures
Config with no lab resource
Config with multiple lab resources
Two resources claiming the same static ip_address on the same network

Errors vs warnings

Outcome	CLI result	Exit code
Missing path	`[ERROR] …` and `path not found`	`1`
Invalid configuration	`[ERROR] …` and `Lab is not valid`	`1`
Warning only	`[WARN] …` then `[SUCCESS] Lab is valid`	`0`
Clean	`[SUCCESS] Lab is valid`	`0`

Valid lab:

instruqt lab validate

==> Validating lab...
    [SUCCESS] Lab is valid

Warning example (layout has an instructions block, but the lab has no content block). The lab is still reported valid:

instruqt lab validate

==> Validating lab...
    [WARN] layout has an instructions block but the lab has no content block - the instructions panel will show no content
    [SUCCESS] Lab is valid

Hard error example (no lab resource):

instruqt lab validate

==> Validating lab...
    [ERROR] config does not contain a lab resource
    Lab is not valid

Debug with lab logs

After the lab is running on the platform, stream runtime logs with instruqt lab logs. This requires authentication via instruqt auth login or the INSTRUQT_TOKEN environment variable.

You can target logs by lab slug or by session ID:

# By team and lab slug
instruqt lab logs <team>/<lab>

# By session (takes precedence over the slug argument)
instruqt lab logs --session <session-id>

Flags:

Flag	Default	Description
`--session`	(empty)	Lab session ID. When set, this is used instead of `team/lab`.
`--since`	`-1m`	Start time as a relative duration (for example `-5m`, `-1h`) or an absolute RFC3339 timestamp.
`--severity`	`INFO`	Log severity.

Examples:

instruqt lab logs my-team/my-lab
instruqt lab logs my-team/my-lab --since -15m
instruqt lab logs --session abc123 --since -5m --severity INFO

For the product UI logs experience, see Logs overview.

Testing checklist

Use this author-oriented sequence before sharing a lab with learners:

Format HCL from the lab directory: instruqt lab format
Validate configuration: instruqt lab validate (fix errors; review warnings)
Push / sync your lab so the platform has the latest version
Start the lab as a learner and walk the full path
Confirm infrastructure (terminals, services, networks) behaves as designed
Confirm tasks and quizzes complete and fail with the feedback you expect
Use logs (instruqt lab logs or the UI) if runtime behavior is wrong

For a step-by-step learner playtest after deployment, follow Testing & Deployment.

Troubleshooting common issues

Path not found when validating:

Confirm the path exists and points at your lab directory or an HCL file
From the lab root, run instruqt lab validate with no arguments

Lab is not valid / unparseable HCL:

Fix syntax errors reported in the CLI output
Run instruqt lab format only after the file is parseable; format fails on unparseable HCL
Re-run instruqt lab validate after each fix

Config does not contain a lab resource:

Ensure exactly one resource "lab" "…" is defined in the config you validate

Config contains multiple lab resources:

Keep a single lab resource per lab project; split separate labs into separate directories

Duplicate static IP on the same network:

Two resources cannot use the same explicit ip_address on the same network
Change one of the addresses or attach the resources to different networks

Warning: layout has instructions but the lab has no content block:

Validation still succeeds (exit 0), but the instructions panel will be empty at runtime
Add lab content (or remove unused instructions blocks from the layout) before publishing

Lab logs cannot find the lab or fails without a stream:

Authenticate with instruqt auth login or set INSTRUQT_TOKEN
Use team/lab in the form <team-slug>/<lab-slug>, or pass --session for a specific session
Widen --since if the activity you care about is older than the default (-1m)

Task validation fails for learners (config validates cleanly):

instruqt lab validate does not execute task check scripts
Test scripts manually in a running lab terminal and review task configuration in the task reference

Project setup — initialize a lab with instruqt lab init
Testing & Deployment — deploy and playtest the learner experience
Task reference — task and condition configuration
Logs overview — platform logs UI