config.yaml

config.yaml в корне проекта хранит умолчания рабочей области; флаги CLI важнее. Файл едет вместе с проектом — в десктоп-приложении правка настройки Project правит этот файл, и он уезжает команде через Publish.

Полный конфиг — flows, includeTags/excludeTags, ai, report — применяется только когда вы передаёте его явно: tapstep test … --config config.yaml. Без флага ближайший config.yaml (подъём вверх от сценария, до домашней директории не доходя) даёт только env:, плюс environments:/defaultEnvironment: для --env-set, exports: для tapstep export и vscode.testspaces для сценариев VS Code.

flows: [flows/]           # где лежат тесты (относительно этого файла)
includeTags: [smoke]      # фильтр по тегам по умолчанию
excludeTags: [wip]

env:                      # общие: доступно как ${VAR} внутри сценариев
  STAGING_URL: https://staging.example.com

defaultEnvironment: staging   # окружение по умолчанию, если прогон не назвал своё
environments:                 # значения по окружениям, коммитятся
  staging:
    BASE_URL: https://staging.example.com
  prod:
    BASE_URL: https://example.com

ai:                       # включает assertWithAI / --analyze
  endpoint: https://ai.internal:8000/v1
  model: qwen3-coder

report:                   # авто-отчёт после каждого прогона
  format: html            # html | junit | json | allure
  output: reports/        # относительно этого файла

exports:                  # куда пишет `tapstep export`
  playwright: playwright
  extester: ../lcp-ui-tests/src/ui-test

Ключи

flows — паттерны относительно папки конфига: файл, папка со сценариями или glob с * (один сегмент) и ** (любая глубина). При прогоне папки они заменяют аргумент-директорию.
includeTags / excludeTags — умолчания для --tags / --exclude-tags (прогоны папки; флаги важнее).
env — общие переменные, ${VAR} внутри сценариев. environments — значения по окружениям, defaultEnvironment — какое берётся, если прогон не назвал своё (ниже).
ai — endpoint, model, необязательный key: любой OpenAI-совместимый сервер (Ollama, vLLM, LM Studio, прокси) или Anthropic с ключом sk-ant-. Включает assertWithAI, assertNoDefectsWithAI, extractTextWithAI и --analyze. Без блока ai: CLI берёт TAPSTEP_AI_ENDPOINT / TAPSTEP_AI_MODEL / TAPSTEP_AI_KEY.
report — format: html|junit|json|allure и output: (папка относительно конфига; по умолчанию html → reports/). После этого каждый прогон пишет туда отчёт без --report; флаг по-прежнему важнее — см. Команды.
http — baseUrl, headers, cookies: общие настройки для всех шагов request: проекта; блок http: флоу лежит поверх, ключ за ключом — см. API-тестирование.
exports — playwright: и extester:, папки, куда пишут tapstep export playwright / tapstep export extester, когда у команды нет -o (чат-тулы и десктоп следуют той же настройке). Путь относительно папки конфига или абсолютный; вне проекта — можно, ради этого всё и сделано: QA-сьют часто живёт в своём репозитории. Обе папки могут совпадать (расширения разные: .spec.ts / .test.ts); корень проекта, папку над ним и папку со сценариями настройка отвергает. Читается из ближайшего config.yaml, --config не нужен. По умолчанию — playwright/ и extester/.
platforms: [web, android, ios] — целевые платформы проекта; подсказка для интерфейса и чата десктопа. CLI принимает и игнорирует.
app: { port, launch } — десктоп-приложение как цель (порт тестового моста, как его запустить); читает десктоп, CLI целится в него через --driver app[:port] — см. Десктоп-приложения.
vscode.testspaces — именованные тестовые окружения VS Code для проектов расширений; сценарий выбирает одно через vscode: { testspace: <name> }, а его собственные vsix/workspace/settings дополняют пробелы. Пути — относительно папки конфига; CLI читает его из ближайшего config.yaml над сценарием, --config не нужен:
```
vscode:
  testspaces:
    full:
      vsix: [fixtures/vsix/a.vsix, fixtures/vsix/b.vsix]
      workspace: fixtures/workspaces/w.zip
      settings: { maven.executable.path: /opt/mvn }
```

Десктоп держит там и несколько своих ключей: kind: vscode помечает проект расширения, ai.provider и ai.privacy настраивают AI-чат.

Переменные и окружения

Тест не должен быть привязан к одному окружению: записали один раз, сегодня гоняете на функциональном тестировании, завтра — на интеграционном. Поэтому проект держит переменные в двух локальностях, и каждая из них либо общая, либо принадлежит одному окружению.

	коммитится	локально (вне git)
общие, для всех окружений	`config.yaml` `env:`	`.env`
одно окружение	`environments.<имя>`	`.env.<имя>`

Настоящие значения — креденшелы и всё, что нельзя коммитить, — живут в локальных файлах (держать в .gitignore) рядом со сценарием или в корне проекта. Сценарии и config.yaml общие, в них живут заглушки. Синтаксис dotenv: KEY=VALUE построчно, комментарии #, пустые строки, необязательный префикс export , парные одинарные или двойные кавычки вокруг значения снимаются.

defaultEnvironment: staging
env:
  RETRIES: "2"              # общее для всех окружений
environments:
  staging: { BASE_URL: https://staging.example.com }
  prod:    { BASE_URL: https://example.com }

tapstep test flows/ --env-set prod выбирает окружение на весь прогон, без флага это делает defaultEnvironment. Имя, которого нет в блоке environments:, — ошибка со списком существующих. Выбранное имя само является переменной — ${TAPSTEP_ENV}, — а вместе с ним подгружается .env.prod, так что локальные секреты окружения едут с ним и не попадают в git.

Значения разрешаются от слабого к сильному:

Слой	Где живёт
умолчания `params:`	шапка самого сценария
`env:` сценария	шапка самого сценария
`env:` конфига	`config.yaml`, коммитится, для всех окружений
`environments.<текущее>`	`config.yaml`, коммитится, для этого окружения — на этом же слое задаётся `${TAPSTEP_ENV}`
`.env`	локально, для всех окружений
`.env.<текущее>`	локально, для этого окружения
`--env-file FILE`	этот прогон
`-e KEY=VAL`	этот прогон

Порядок задают два правила: значение окружения бьёт общее на том же уровне, а локальный файл бьёт закоммиченный. (До 0.13.3 .env стоял ниже --env-set; теперь локальные секреты выигрывают у закоммиченных значений.) Сам --env-set слоем не является — он выбирает, каким будет <текущее>; -e TAPSTEP_ENV=… всё равно перебьёт имя, которое читает шаг, потому что это имя — обычное значение слоя окружения. Любой ${NAME}, который не задал ни один слой, берётся из окружения процесса.

Ближайшие config.yaml и .env находятся подъёмом вверх от сценария. Подъём останавливается перед домашней директорией, поэтому сценарий, лежащий прямо в ~, не относится ни к какому проекту — config.yaml рядом с ним в ~ не читается; сценарий папкой ниже (~/work/flows/a.flow.yaml) разрешает ~/work как обычно. С --config его env: и environments: заменяют ближайшие. Отсутствующий .env молча пропускается, отсутствующий --env-file — ошибка. tapstep test применяет всю цепочку; MCP-инструмент run_flow разрешает её для defaultEnvironment проекта.

Окружение, против которого шёл прогон, попадает в отчёт: поле environment в JSON, <property name="environment"> в JUnit, лейбл environment в Allure и шапка HTML-отчёта. tapstep validate предупреждает про ${VAR}, который окружение не разрешает, и называет какое, — это и есть проверка, ловящая тест, записанный на одном окружении, до того как его запустят на другом. Хелперы не проверяются: они выполняются только внутри теста, а их переменные приходят из env: у вызывающего runFlow.

Значение может содержать JS-выражение — EMAIL: "qa+${Date.now()}@example.com" — оно вычисляется один раз, до первого шага, и запоминается: свежее на каждый прогон и одинаковое во всех шагах, которые его читают. env: у runFlow разрешается так же, один раз на блок; сломанное выражение валит прогон с именем ключа.

env.STAGING_URL — адрес, который Запись в десктопе использует как Staging-цель проекта: записанные сценарии начинаются с openLink: ${STAGING_URL}, поэтому сменить staging для всех тестов сразу — правка в одну строку.