Repository navigation
Writing Tests RU
Тест 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 предсказывает, что харнесс загрузит, только по файлам проекта. Он ничего не запускает и отвечает за миллисекунды. Тест ниже взят из фикстур самого 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 запускает настоящий харнесс против 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 ваш тест играет роль модели. Он велит харнессу прочитать файл, ждёт следующий запрос и проверяет, что харнесс добавил в контекст:
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. По списку объектов он регистрирует по тесту на элемент, а {поле} в имени заменяется значением элемента:
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);
});Список путей к правилам устаревает в тот же день, когда кто-то добавляет новое правило. 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 прогоняет промпт несколько раз и считает:
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-процентный интервал Уилсона и судит по интервалу, а не по голой доле:
-
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 показывает, какие промпты получены из какого файла.
Сценарий даёт агенту задачу и проверяет, что тот сделал. Тело выполняется по разу на каждый прогон и получает этот 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:
Каждый тест указывает свой 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.
| Экспорт | Что это |
|---|---|
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.
| Опция | Тип | По умолчанию | Слои | Значит |
|---|---|---|---|---|
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.
| Поле | 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 в захваченные списки не попадает.
| Член | Делает |
|---|---|
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.
runs — массив прогонов с runs.positive и runs.negative. У прогона есть prompt, sample, skills, rules, tools ({ name, input }, от первого к последнему), changed, turns, cut, loadout, added (что подключилось после первого запроса) и error, если сломалась сама сессия.
| Член | Значит |
|---|---|
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 или вы |
Да |
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие
{ "$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" }] } ] } ] }