lexq-simulation

LexQ CLI — Simulation & Testing

Prerequisite: Read lexq-shared/SKILL.md first.

Overview

LexQ provides three levels of pre-deploy validation:

Tool	Scope	When to Use
Dry Run	Single input	Quick validation of one scenario
Dry Run Compare	Single input, two versions	Side-by-side version comparison
Simulation	Batch (historical data)	Full regression test before deploy

Golden rule: Always dry-run before publishing, always simulate before deploying to production.

1. Requirements Analysis

Before testing, check what facts a version expects:

lexq analytics requirements --group-id <gid> --version-id <vid>

Response includes:

{
  "groupId": "...",
  "versionId": "...",
  "versionNo": 3,
  "requiredFacts": [
    {
      "key": "paymentAmount",
      "type": "NUMBER",
      "required": true,
      "usedBy": [
        "VIP Discount",
        "Premium Block"
      ]
    },
    {
      "key": "customerTier",
      "type": "STRING",
      "required": true,
      "usedBy": [
        "VIP Discount"
      ]
    }
  ],
  "exampleRequest": {
    "facts": {
      "paymentAmount": 0,
      "customerTier": ""
    },
    "context": {}
  }
}

Always run this before dry-run. Copy exampleRequest.facts as your starting template and fill in real values.

exampleRequest.context comes back empty, and it stays empty even when the group has an A/B test running. Live execution requests against such a group also need context.trafficKey or the test version receives no traffic — see the A/B testing section of the groups skill. Dry-run itself is unaffected: it always evaluates the version you name, so routing never applies here.

2. Dry Run (Single Input)

Test a single set of facts against a version:

lexq analytics dry-run --version-id <vid> --json '{
  "facts": {
    "paymentAmount": 150000,
    "customerTier": "VIP"
  }
}'