Skip to content

Writing Tests RU

Pavel Erokhin edited this page Nov 16, 2026 · 2 revisions

English version

Тест ctxray описывает, что должно быть в контексте вашего агента, и проверяет это на каждом ИИ-харнессе, с которым вы работаете. Вы пишете его один раз, а ctxray запускает его на Claude Code, Codex и остальных: по ячейке на харнесс. Эта страница начинает с проверки одного правила и доводит её до теста, который задаёт настоящей модели сотню промптов. В справочнике в конце собраны все функции, опции и матчеры.

Каждый вид теста проверяет свой слой Loadout Stack: test.resolve — L3, test.assemble — L4, test.wire — L5, test.activate — L6, test.scenario — L7. Для L1 Lint и L2 Policy тесты не нужны: ctxray прогоняет их при каждом ctxray test, подробности — на странице Policies.

Файлы тестов

ctxray находит в репозитории все файлы *.ctxray.ts. Подходят и .js, .mjs, .cjs, .mts, .cts, а в *.ctxray.jsonc (или .json) живут декларативные тесты. Файлы, которые скрывает .gitignore, включая node_modules, в прогон не попадают. Если запустить ctxray test из подпапки, выполнятся только тесты внутри неё. Конфиг ctxray читает из папки, в которой его запустили, поэтому из подпапки укажите корневой: --config ../ctxray.config.ts.

Файл теста импортирует API из @mairwunnx/ctxray:

import { corpus, discover, expect, suite, test } from "@mairwunnx/ctxray";

Этот модуль файлу отдаёт сам ctxray, поэтому тест работает вообще без node_modules. npm-пакет нужен только редактору, ради типов:

npm install -D @mairwunnx/ctxray

Если версия установленного пакета расходится с версией исполняемого файла ctxray, прогон об этом скажет: «В node_modules лежит @mairwunnx/ctxray 0.1.0, а тесты запускает этот ctxray, 0.2.0». Тогда редактор сверяет код с API, которого ctxray может и не знать.

ctxray init кладёт первый тест в ctxray/loadout.ctxray.ts.

Первый тест: L3

L3 предсказывает, что харнесс загрузит, только по файлам проекта. Он ничего не запускает и отвечает за миллисекунды. Тест ниже взят из фикстур самого ctxray: правила о платежах должны загружаться, когда агент работает с платёжным кодом.

import { expect, suite, test } from "@mairwunnx/ctxray";

suite("payments", { fixture: "../payments" }, () => {
  test.resolve("payments rules attach to payment sources", { requires: ["pathRules"] }, async ({ resolve }) => {
    const l = await resolve({ cwd: "app", files: ["app/src/main/kotlin/payments/Charge.kt"] });
    expect(l.rules).toInclude([".claude/rules/kotlin.md", ".claude/rules/payments.md"]);
    expect(l.rules).not.toInclude(".claude/rules/web.md");
    expect(l.rules.get(".claude/rules/payments.md").reason).toBe("glob:**/payments/**/*.kt");
  });
});

suite объединяет тесты под общим именем. Его fixture указывает проект, на который смотрят тесты, относительно файла теста. Без него тесты смотрят на сам репозиторий, а вложенные suite наследуют фикстуру родителя.

resolve() принимает папку, в которой стартует агент (cwd), и файлы, с которыми он работает (files), — обе относительно корня проекта. Он возвращает Loadout, который собрал бы харнесс: rules, skills.listed, skills.loaded, mcp.servers, commands и tokens. В каждом списке запись можно найти по пути или имени: l.rules.get(".claude/rules/payments.md") вернёт правило с его activation, reason и tokens. Если такого id в списке нет, тест падает и перечисляет, что в списке есть.

У Codex нет правил, которые загружаются по пути, поэтому requires: ["pathRules"] пропускает его, а не роняет тест. Запустите слой:

ctxray test --layer L3
 ctxray 0.1.0  ·  2 харнесса  ·  бэкенд: mock

 payments  payments
   L3 resolve  payments rules attach to payment sources
               claude-code ✓   codex ○ нужно pathRules

Когда ожидание не выполняется, ctxray показывает, что ждал и что нашёл:

 ✗ claude-code › demo › web rule stays out
     expect(received).toInclude(expected)
     Нет        .claude/rules/web.md
     Получено   CLAUDE.md, AGENTS.md, .claude/rules/style.md, app/CLAUDE.md, app/AGENTS.md, …

Разные харнессы — разные файлы

Харнессы читают разные файлы: Claude Code берёт CLAUDE.md, Codex — AGENTS.md. expect.on оставляет ожидания только для некоторых харнессов:

test.resolve("instructions of the app load in app", async ({ resolve }) => {
  const l = await resolve({ cwd: "app" });
  expect(l.rules).toInclude("app/AGENTS.md");
  expect.on("codex", () => expect(l.rules).toInclude("AGENTS.md"));
  expect.on("claude-code", () => expect(l.rules).toInclude(["CLAUDE.md", "app/CLAUDE.md"]));
});

Тело теста получает и harness — id харнесса, на котором оно выполняется. ctxray init так выбирает корневой файл каждого харнесса:

const rootRules: Record<string, string> = { "claude-code": "CLAUDE.md", codex: "AGENTS.md" };

suite("loadout", () => {
  test.resolve("the root rules file loads for every file", async ({ harness, resolve }) => {
    const loadout = await resolve({ files: ["README.md"] });
    expect(loadout.rules).toInclude(rootRules[harness]);
  });
});

Какие файлы читает каждый харнесс и что он умеет, описано на странице Harnesses.

Снапшоты

Снапшот хранит весь Loadout целиком, поэтому любое его изменение видно на ревью. toMatchLoadoutSnapshot() сравнивает Loadout с сохранённым:

const l = await resolve({ cwd: "app" });
expect(l).toMatchLoadoutSnapshot();

Первый прогон падает с «Снапшот … ещё не записан»: сам по себе тест ваши файлы не пишет. Запишите снапшоты явно и закоммитьте их:

ctxray test -u

Они ложатся рядом с файлом теста: снапшоты payments.ctxray.ts хранятся в __snapshots__/payments.ctxray.snap.json. Ключ состоит из suite, теста, харнесса и его версии: payments › instructions of the app load in app › claude-code@static. L3 только читает файлы, поэтому его версия — static. В снапшоте L4 или L5 стоят версия харнесса и модель, так что обновление харнесса само меняет ключ.

Снапшот L3 хранит каждое правило с его activation, reason и токенами, каждый скилл, MCP-серверы, команды и токены по компонентам. Если Loadout изменился, ctxray называет каждое значение, которое сдвинулось:

 ✗ claude-code › payments › instructions of the app load in app
     Loadout расходится со снапшотом «payments › instructions of the app load in app › claude-code@static»
     Изменилось  rules › app/CLAUDE.md › tokens  23 → 40
     Изменилось  tokens › rules  115 → 132

Снапшот L4 или L5 хранит только имена: секции системного промпта, правила, скиллы, MCP-серверы с их инструментами и команды. Токены в захваченном запросе меняются вместе с датой и путями, а имена — нет.

L4: контекст на старте сессии

L4 запускает настоящий харнесс против mock-модели ctxray и берёт его первый запрос. Так видно то, чего не знает L3: системный промпт, встроенные инструменты и схемы инструментов MCP. Mock-модель ничего не стоит и всегда отвечает одинаково. Харнесс должен лежать в PATH или быть закреплён в ctxray.lock, как описано на странице Harnesses.

test.assemble("context budget", async ({ assemble }) => {
  const l = await assemble({ cwd: "app" });
  expect(l.tokens.total).toBeLessThan(25_000);
  expect(l.tokens.byMcpServer("jira")).toBeLessThan(3_000);
  expect(l.mcp.servers).toEqual(["github", "jira"]);
  expect(l).toMatchLoadoutSnapshot();
});

assemble() возвращает захваченный Loadout. Помимо того, что показывает L3, в нём есть system (секции системного промпта), mcp.tools, duplicates, version и model харнесса и tokens.total. tokens.byMcpServer(name) говорит, во что обходится один сервер, когда загружаются его инструменты. tokens.exact равен true, только если токены посчитал провайдер. Иначе это локальная оценка, и отчёт помечает её знаком ≈.

toEqual сравнивает список записей со списком id по порядку, поэтому ["github", "jira"] читается как имена серверов.

Чтобы удержать стартовый контекст в лимите, тест не нужен. Каждый ctxray test, в слоях которого есть L4, один раз запускает каждый харнесс и сверяет стартовый контекст с maxTokens ваших политик.

L5: что загружается по ходу сессии

В L5 ваш тест играет роль модели. Он велит харнессу прочитать файл, ждёт следующий запрос и проверяет, что харнесс добавил в контекст:

test.wire("nested instructions load on read", { requires: ["pathRules"] }, async ({ session }) => {
  await session.model.calls("Read", { path: "app/src/main/kotlin/payments/Charge.kt" });
  const next = await session.nextRequest();
  expect(next.loadout.rules).toInclude("app/src/main/kotlin/payments/AGENTS.md");
  expect(next).toAgreeWithResolver();
});

session.model.calls(tool, input) отвечает на последний запрос харнесса вызовом инструмента. Read с path и Skill работают на любом харнессе: ctxray переводит их в собственный инструмент харнесса. session.model.says(text) отвечает текстом. session.nextRequest() ждёт следующий запрос, а session.firstRequest() возвращает первый.

В запросе есть loadout (захваченный Loadout на этот момент), added (правила и скиллы, которые принёс этот запрос) и predicted (что ожидает L3 для той же папки и уже прочитанных файлов). С запросом работают два матчера:

  • toLoadRule(rule) проверяет, что правило в контексте на этом запросе. С .not — что этот запрос правило не принёс, поэтому правило, загруженное раньше, не роняет следующее чтение.
  • toAgreeWithResolver() проверяет, что харнесс загрузил те правила и скиллы проекта, которые предсказывает L3. Если нет, ctxray сообщает о дрейфе резолвера: харнесс изменил поведение, и адаптер ctxray для него пора обновить.

session.events() возвращает собственный поток событий харнесса, например stream-json у Claude Code. startSession({ cwd, prompt }) открывает в том же тесте ещё одну сессию. Когда тело теста завершается, ctxray закрывает все сессии. Если харнесс вышел с ошибкой или попытался выйти в интернет в обход ctxray, тест падает.

Один тест — много случаев: .each

У каждого вида теста есть .each. По списку объектов он регистрирует по тесту на элемент, а {поле} в имени заменяется значением элемента:

test.resolve.each([
  { file: "app/src/main/kotlin/payments/Charge.kt", rule: ".claude/rules/payments.md" },
  { file: "app/src/main/kotlin/web/Page.kt", rule: ".claude/rules/kotlin.md" },
])("{rule} loads for {file}", { requires: ["pathRules"] }, async ({ file, rule, resolve }) => {
  expect((await resolve({ files: [file] })).rules).toInclude(rule);
});

Правила, которые ctxray найдёт сам

Список путей к правилам устаревает в тот же день, когда кто-то добавляет новое правило. discover.rules() выбирает правила и скиллы по тому, что они собой представляют:

Селектор Выбирает
owner Правила, чей владелец в CODEOWNERS совпадает, например "@acme/payments", или список владельцев. ctxray ищет .github/CODEOWNERS, .gitlab/CODEOWNERS, CODEOWNERS и docs/CODEOWNERS
under Правила внутри папки или под глобом, относительно корня проекта
activation always, path, intent или manual, либо их список

.where() сужает выборку дальше. Выборка вычисляется внутри каждого теста, потому что набор правил зависит от харнесса. Пустая выборка роняет тест: иначе опечатка в селекторе прошла бы как тест, который ничего не проверяет.

const payments = discover.rules({ owner: "@acme/payments" });

suite("payments rules", { fixture: "../payments" }, () => {
  test.resolve.each(payments.where({ activation: "path" }))(
    "{rule.path} attaches to matching files",
    { requires: ["pathRules"] },
    async ({ rule, resolve }) => {
      for (const file of rule.matchingFiles({ sample: 3 })) {
        expect((await resolve({ files: [file] })).rules).toInclude(rule);
      }
      const other = rule.nonMatchingFile();
      if (other) expect((await resolve({ files: [other] })).rules).not.toInclude(rule);
    },
  );
});

.each по набору правил даёт каждому тесту rule. rule.matchingFiles({ sample: 3 }) возвращает три файла проекта, к которым правило относится, равномерно по списку, а rule.nonMatchingFile() — один, к которому не относится. toInclude принимает правило, набор правил, путь или список путей.

Та же выборка работает в L4 и L5. root набора — папка, где лежат его правила, удобное место для старта агента:

test.assemble("always rules present in payments zone", async ({ assemble }) => {
  const always = payments.where({ activation: "always" });
  const l = await assemble({ cwd: always.root });
  expect(l.rules).toInclude(always);
});

L6: выберет ли модель скилл?

Скилл загружается, когда модель решает, что он подходит к промпту. Проверить это может только модель, которая отвечает сама, поэтому L6 прогоняет промпт несколько раз и считает:

test.activate(
  "refund prompt → refunds skill",
  { prompt: "Make a partial refund of 40 EUR for order 123.", samples: 5, requires: ["skills"] },
  ({ runs }) => {
    expect(runs).skill("refunds").toActivate({ min: 0.5 });
    expect(runs).skill("payouts").not.toActivate({ max: 0.5 });
  },
);

Каждый сэмпл — целая сессия: харнесс получает промпт и работает, пока не остановится или не упрётся в лимит turns, после которого ctxray отвечает вместо модели. Затем тело теста видит все прогоны. expect(runs).skill(name), .rule(path) и .anyOf(set) считают прогоны, в которых загрузился скилл, правило или что-то из набора.

L6 нужна модель. С бэкендом mock, который стоит по умолчанию, тест показывает «нужен --backend replay или real» и пропускается. Оба бэкенда описаны в разделе Бэкенды и кассеты.

Доверительный интервал

Десять прогонов из десяти ещё не доказывают долю 90 %. ctxray строит вокруг доли 95-процентный интервал Уилсона и судит по интервалу, а не по голой доле:

Четыре результата на шкале от 0 до 1. 16 из 16 проходит min 0,8: нижняя граница интервала 0,81. 14 из 16 не определён: доля 0,88 выше 0,8, но нижняя граница 0,64. 9 из 16 падает: доля 0,56 ниже 0,8. 0 из 16 проходит max 0,2: верхняя граница 0,19. Безупречному результату нужно 4 прогона для 0,5, 16 для 0,8, 35 для 0,9 и 73 для 0,95.

  • toActivate({ min }) проходит, когда нижняя граница интервала достигает min.
  • .not.toActivate({ max }) проходит, когда верхняя граница не выше max.
  • Тест падает, когда сама доля по неверную сторону порога.
  • Иначе сэмплов пока мало, и тест получает статус не определён (inconclusive). ctxray называет, сколько сэмплов всего решили бы вопрос, если доля сохранится.
skill(refunds) загружался с долей 1.00 [0.72–1.00, ДИ 95 %]: сэмплов пока мало, чтобы судить
  Сколько всего сэмплов нужно  skill(refunds): 35

Без порога toActivate() означает { min: 0.8 }, а .not.toActivate() — { max: 0.2 }. Без samples тест делает столько прогонов, сколько нужно, чтобы их доказать: 16 на каждую группу промптов, то есть на одиночный prompt, на список positive и на список negative. ctxray делит прогоны группы между её промптами с округлением вверх, так что два позитивных промпта прогоняются по 8 раз. Явный samples важнее и считается на каждый промпт.

Прежде чем выбрать порог строже, посчитайте прогоны. Даже когда скилл загрузился в каждом прогоне, нижняя граница достигает 0,5 за 4 прогона, 0,8 за 16, 0,9 за 35 и 0,95 за 73. Раздел activate в конфиге задаёт пороги и число прогонов для всего проекта. Поднимите в нём min до 0,9 — и число прогонов по умолчанию само вырастет до 35. Порог, который вы передали в toActivate({ … }), по-прежнему важнее конфига.

Неопределённый тест прогон не роняет. Сломавшиеся сессии (харнесс упал, кассета кончилась) ничего не говорят о модели, поэтому ctxray их не считает. Если сломались все, ошибка первой становится ошибкой теста.

Корпус промптов

Один промпт говорит об одной формулировке. Корпус даёт тесту много: промпты, которые должны выбрать скилл (positive), и пограничные, которые не должны (negative). Положите их в модуль, чей default export содержит оба списка, или в JSON-файл:

// tests/prompts/payments.ts
export default {
  positive: ["Refund order 123 in part", "Pay the seller out for last week"],
  negative: ["Rename the Android build flavour"],
};

corpus() загружает файл относительно файла теста ещё до запуска тестов. runs.positive и runs.negative содержат прогоны каждого списка. Каждый список получает свои 16 прогонов, поэтому ниже два позитивных промпта прогоняются по 8 раз, а негативный — 16:

import { corpus, discover, expect, suite, test } from "@mairwunnx/ctxray";

const payments = discover.rules({ owner: "@acme/payments" });
const prompts = corpus("./prompts/payments.ts");

suite("payments rules", { fixture: "../payments" }, () => {
  test.activate(
    "payments intents activate payments skills",
    { positive: prompts.positive, negative: prompts.negative },
    ({ runs }) => {
      expect(runs.positive)
        .anyOf(payments.where({ activation: "intent" }))
        .toActivate();
      expect(runs.negative)
        .anyOf(payments.where({ activation: "intent" }))
        .not.toActivate();
    },
  );
});

Писать сотню промптов руками долго. ctxray gen-prompts просит модель написать их по описанию каждого скилла и каждого правила, которое модель выбирает по описанию:

ctxray gen-prompts --from-descriptions --out tests/prompts/intents.json

Команда пишет --count позитивных и столько же негативных промптов на правило или скилл (по умолчанию 5) моделью claude-opus-5-5 через ваш upstream и ключ. Другую модель задаёт --model, но не ту, что под тестом: модель, которая сама пишет себе экзамен, сдаёт его слишком легко, и ctxray об этом предупреждает. Прочитайте файл, прежде чем тест им воспользуется. Корпус не меняется, пока вы не перепишете его, а существующий файл перезаписывается только с --force.

{
  "model": "claude-opus-5-5",
  "generated": "2026-11-16",
  "positive": ["…"],
  "negative": ["…"],
  "by": { ".claude/skills/refunds/SKILL.md": { "positive": ["…"], "negative": ["…"] } }
}

corpus() читает списки positive и negative верхнего уровня. by показывает, какие промпты получены из какого файла.

L7: сценарии

Сценарий даёт агенту задачу и проверяет, что тот сделал. Тело выполняется по разу на каждый прогон и получает этот run:

test.scenario(
  "a partial refund goes through the refunds skill",
  { prompt: "Make a partial refund of 40 EUR for order 123.", samples: 3, min: 0.6, requires: ["skills"] },
  ({ run }) => {
    expect(run.skills).toInclude("refunds");
    expect(run.changed).not.toInclude("app/build.gradle.kts");
    // Инструменты у каждого харнесса свои: Claude Code читает через Read, Codex через exec_command.
    expect.on("claude-code", () => expect(run.tools).toInclude("Read"));
  },
);

В прогоне есть prompt и номер sample, skills и rules, дошедшие до модели, вызванные по порядку tools, изменённые файлы changed, число turns, флаг cut (ответил ли ctxray на последний ход вместо модели) и loadout последнего запроса. turns здесь по умолчанию 30. Без min должен пройти каждый прогон. С min доля прошедших прогонов проходит через тот же интервал, что и в L6.

Бэкенды и кассеты

Бэкенд решает, кто отвечает харнессу:

Бэкенд Кто отвечает Что выполняется
mock Ваш тест или никто. По умолчанию L3, L4, L5. L6 и L7 пропускаются
real Провайдер модели или ваш шлюз L3–L7
replay Ответы, записанные раньше с real L3–L7

L4 и L5 всегда работают на mock-модели, какой бы бэкенд вы ни выбрали: она бесплатна и детерминирована.

Настоящий прогон стоит денег, поэтому запишите его один раз и проигрывайте в каждом merge request:

ctxray test --layer L6-L7 --backend real --record
ctxray test --backend replay

--record пишет ответы модели рядом с файлом теста, по файлу на харнесс: __cassettes__/activate.ctxray.ts.claude-code.json. Закоммитьте их. Секреты ctxray вычищает до того, как кассета попадёт на диск. Каждая запись привязана к имени теста, позиции промпта и номеру сэмпла. Переименовали тест или переставили промпты — запишите заново.

При replay харнесс работает по-настоящему, а на каждый ход ctxray отвечает с кассеты. Если харнесс пошёл не тем путём, что при записи, прогон падает с промахом кассеты. Обычно это значит, что изменился харнесс или ваши файлы. Перезапишите кассету с --backend real --record.

Настоящий прогон берёт ключ провайдера из CTXRAY_UPSTREAM_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY или GEMINI_API_KEY и перестаёт тратить, когда бюджет исчерпан. upstream, budget, prices и именованные бэкенды описаны в Configuration, шлюзы — в Enterprise.

Декларативные тесты

Простым проверкам TypeScript не нужен. Файл *.ctxray.jsonc хранит наборы тестов как данные, и ctxray превращает каждый в такой же тест, какой регистрирует DSL:

{
  "$schema": "https://github.com/MairwunNx/ctxray/releases/latest/download/tests.schema.json",
  "suites": [
    {
      "name": "payments",
      "fixture": "../payments",
      "tests": [
        {
          "name": "kotlin rule on Kotlin files",
          "layer": "L3",
          "requires": ["pathRules"],
          "files": ["app/src/main/kotlin/payments/Charge.kt"],
          "expect": {
            "rules": { "include": [".claude/rules/kotlin.md"], "exclude": [".claude/rules/web.md"] },
            "tokens": { "total": { "lessThan": 25000 } }
          }
        },
        {
          "name": "nested instructions load on read",
          "layer": "L5",
          "requires": ["pathRules"],
          "steps": [
            {
              "read": "app/src/main/kotlin/payments/Charge.kt",
              "expect": { "rules": { "include": ["app/src/main/kotlin/payments/AGENTS.md"] }, "agreeWithResolver": true }
            }
          ]
        },
        {
          "name": "refund prompt → refunds skill",
          "layer": "L6",
          "corpus": "./prompts/intents.json",
          "expect": [{ "skill": "refunds", "min": 0.8, "runs": "positive" }]
        }
      ]
    }
  ]
}

Каждый тест указывает свой layer. Списки принимают include, exclude и equal, числа — lessThan, atMost, moreThan и atLeast. L3 и L4 ожидают rules, skills.listed, skills.loaded, mcp.servers, commands, tokens и snapshot. Шаг L5 делает одно действие — read, call или say — и может через expect проверить следующий запрос. Ожидание L6 называет skill, rule или anyOf с min или max, а runs выбирает all, positive или negative. L7 ожидает changed, tools, skills и rules. Полная схема лежит в ассете релиза tests.schema.json, и редактор по ней подсказывает.

Запуск тестов

ctxray test                              # все слои, которые позволяет бэкенд, все харнессы из конфига
ctxray test --layer L1-L3                # только файлы: ни один харнесс не запускается
ctxray test --harness claude-code        # один харнесс
ctxray test --filter "payments rules"    # тесты, в имени которых есть этот текст
ctxray test --watch                      # заново после каждого изменения

--filter ищет текст в полном имени вместе с suite, без учёта регистра. Собственные проверки ctxray — L1, L2 и стартовый контекст L4 — выполняются при любом фильтре, их ограничивает --layer. --watch (-w) перезапускает тесты вскоре после сохранения файла, Enter запускает сразу, q останавливает. Изменения в .git, node_modules, .ctxray, __snapshots__, __cassettes__ и папке отчётов прогон не запускают.

Каждая ячейка получает статус:

Статус Значит Роняет прогон
пройден Все ожидания выполнены Нет
упал Ожидание не выполнено, тело бросило ошибку или кончилось время Да
нестабилен Упал, а потом прошёл на повторе Нет
не определён L6 или L7 не хватило сэмплов Нет
пропущен filtered из-за --layer или --filter, unsupported харнессом («нужно pathRules»), unavailable здесь, ждёт backend («нужен --backend replay или real») или кончился budget Нет

Все флаги ctxray test собраны на странице Commands, а HTML, JUnit и Markdown — в Reporters and Reports.

Справочник

Экспорты @mairwunnx/ctxray

Экспорт Что это
suite(name, options?, body) Объединяет тесты. options.fixture — папка проекта относительно файла теста. Тело должно регистрировать тесты сразу: async-тело роняет файл
test.resolve, test.assemble, test.wire, test.activate, test.scenario Регистрируют тест L3, L4, L5, L6 или L7: (name, options?, body)
test.<kind>.each(items) (name, options?, body) по разу на объект или на правило из набора
expect(value) Матчеры, см. ниже
expect.on(harnesses, body) Выполняет body только на этих харнессах: один id или список. Возвращает результат body, так что асинхронный нужно await
discover.rules(selector?) Набор правил, который вычисляется внутри каждого теста
corpus(path) Промпты из модуля или JSON-файла относительно файла теста
defineConfig(config) Типы для ctxray.config.ts, см. Configuration

Типы: TestOptions, SuiteOptions, Rule, RuleSet, RuleSelector, ResolvedLoadout, ResolveRequest.

Виды тестов

Вид Слой Тело получает Таймаут по умолчанию
test.resolve L3 resolve({ cwd?, files? }) 30 с
test.assemble L4 assemble({ cwd?, prompt? }) 120 с
test.wire L5 session, startSession({ cwd?, prompt? }) 120 с
test.activate L6 runs 300 с на сэмпл
test.scenario L7 run 300 с на сэмпл

Каждое тело получает ещё harness, а внутри .each — поля элемента или rule.

TestOptions

Опция Тип По умолчанию Слои Значит
requires Capability[] [] все Харнесс без одной из этих возможностей пропускает тест как unsupported: skills, pathRules, intentRules, mcp, hooks, headless, proxyable
retries number 0 все Повторяет тест после падения. Если повтор прошёл, тест нестабилен
timeout number (мс) см. выше все Для L6 и L7 ограничивает каждый сэмпл, а не весь тест
cwd string корень проекта L4–L7 Где стартует харнесс, относительно корня проекта
prompt string — L6, L7 Промпт
positive string[] [] L6, L7 Промпты, которые должны загрузить проверяемое, в runs.positive
negative string[] [] L6, L7 Промпты, которые не должны, в runs.negative
samples number 16 на группу промптов (L6), 1 (L7) L6, L7 Прогонов на промпт. Без него L6 делит activate.runs из конфига между промптами каждой группы
turns number 2 (L6), 30 (L7) L6, L7 Ходов модели, после которых ctxray отвечает вместо неё
min number все прогоны L7 Доля прогонов, которые должны пройти

L6 и L7 нужен хотя бы один из prompt, positive и negative.

Loadout

Поле L3 resolve() L4 assemble(), L5 request.loadout
harness ✓ ✓
cwd, files ✓
version, model ✓
system ✓
rules, commands ✓ ✓
skills.listed, skills.loaded ✓ ✓
mcp.servers ✓ ✓
mcp.tools (id server/tool) ✓
duplicates ✓
tokens.known ✓
tokens.total, tokens.byMcpServer(name), tokens.framing ✓
tokens.byComponent, tokens.exact, tokens.method ✓ ✓

Каждый список — массив с методом .get(id), который ищет запись по пути или имени. У правила есть path, activation, reason и tokens, у скилла — name, path, builtin и tokens. L3 не знает системного промпта, инструментов и схем MCP, поэтому tokens.known учитывает только правила, скиллы и команды. Собственный плагин ctxray в захваченные списки не попадает.

Сессия (L5)

Член Делает
firstRequest() Первый запрос сессии
nextRequest() Запрос, который следует за последним ответом
model.calls(tool, input?) Отвечает вызовом инструмента. Read с path и Skill работают на любом харнессе
model.says(text) Отвечает текстом
events() Собственные события харнесса, например stream-json у Claude Code и --json у Codex
end() Завершает сессию. ctxray всё равно вызовет его после тела теста

У запроса есть index, loadout, added.rules, added.skills, predicted, raw и snapshot.

Прогоны (L6, L7)

runs — массив прогонов с runs.positive и runs.negative. У прогона есть prompt, sample, skills, rules, tools ({ name, input }, от первого к последнему), changed, turns, cut, loadout, added (что подключилось после первого запроса) и error, если сломалась сама сессия.

Rule и RuleSelector

Член Значит
RuleSelector.owner Владелец из CODEOWNERS или их список
RuleSelector.under Папка или глоб относительно корня проекта
RuleSelector.activation always, path, intent, manual или их список
RuleSet.where(selector) Более узкий набор
RuleSet.rules Выбранные правила, внутри теста
RuleSet.root Папка из under или общая папка правил
Rule.path, Rule.dir Файл и папка, к которой он относится
Rule.activation, Rule.globs Как правило загружается, и его глобы
Rule.matchingFiles({ sample? }) Файлы проекта, к которым оно относится, равномерно по списку
Rule.nonMatchingFile() Один файл проекта, к которому оно не относится, или undefined

Инструкции без глобов считаются always, с глобами — path. Скиллы, которые харнесс показывает модели, считаются intent, остальные — manual.

Матчеры

Матчер Принимает Проверяет
toBe(value) что угодно Object.is
toEqual(value) что угодно Глубокое равенство. Список записей равен списку id в том же порядке
toBeDefined(), toBeUndefined() что угодно
toBeLessThan(n), toBeLessThanOrEqual(n) число
toBeGreaterThan(n), toBeGreaterThanOrEqual(n) число
toHaveLength(n) что-то с length
toMatch(text или RegExp) строку Подстроку или совпадение
toInclude(ids) список Есть каждый id: путь, имя, правило, набор правил или список. С .not — нет ни одного
toMatchLoadoutSnapshot() Loadout Совпадает с сохранённым снапшотом. Без .not
toLoadRule(rule) запрос L5 Правило в контексте. С .not — этот запрос его не принёс
toAgreeWithResolver() запрос L5 Харнесс загрузил то, что предсказывает L3. Без .not
skill(name).toActivate({ min }) прогоны Нижняя граница интервала достигает min, по умолчанию 0,8 или activate.min из конфига
rule(path).toActivate({ min }) прогоны То же для правила
anyOf(set).toActivate({ min }) прогоны То же для любого из набора правил или списка путей и имён
….not.toActivate({ max }) прогоны Верхняя граница не выше max, по умолчанию 0,2 или activate.max из конфига

У матчеров есть форма с .not, если таблица не говорит иного. Матчеры активации ставят .not перед toActivate.

Файлы рядом с тестами

Путь Кто пишет Коммитить
__snapshots__/<имя>.ctxray.snap.json ctxray test -u Да
__cassettes__/<имя>.ctxray.ts.<харнесс>.json ctxray test --backend real --record Да
корпус, например prompts/intents.json ctxray gen-prompts или вы Да

Clone this wiki locally