DocsHow briefs work
04 / 04

How briefs work

How a brief is structured and how a run moves through it.

Brief structure

Every brief has these components:

  • Title & summary - What you'll learn and build
  • Instructions - Detailed requirements and expected behavior
  • Test cases - Scenarios your solution must handle
  • Mock APIs - If required, documentation for available APIs

Test lifecycle

When you run tests, here's what happens:

  1. Trigger - Nodox sends a POST request to your webhook URL
  2. Processing - Your webhook processes the payload (and calls mock APIs if needed)
  3. Response - Your webhook POSTs the result to the callback URL
  4. Validation - Nodox compares your response to the expected output
Timeout

You have 30 seconds to respond. If no callback is received, the test times out.

Passing tests

To pass a brief, all test cases must succeed. Each test validates:

  • Correct response structure (proper JSON with x-nodox-token header)
  • Expected output values
  • Proper API calls (if the brief requires them)