Configuration Reference

This document lists every configuration parameter currently supported by Zero QA across all supported scopes:

• user config (~/.config/zero-qa/config.yaml, overrides code defaults in GlobalDefaultsConfig)
• scenario-level configuration in zero-qa.yaml or any YAML passed through --scenario
• suite-level configuration inside zero-qa.yaml
• command-line flags

User Configuration

Zero QA works out of the box with no configuration file. All defaults are defined in code (GlobalDefaultsConfig).

To override code defaults, create a user config file at ~/.config/zero-qa/config.yaml (or $XDG_CONFIG_HOME/zero-qa/config.yaml). Only include the keys you want to change:

# ~/.config/zero-qa/config.yaml
defaults:
  agent_type: claude_code
  agent_model: sonnet
  run_base_dir: ~/zero-qa-runs

Unspecified keys keep their code defaults.

Naming Principle

• Each semantic parameter has one canonical name, and that name is scope-independent.
• The same semantic parameter must keep the same canonical name across user config, scenario config, suite config, and CLI documentation.
• Parameters with different semantics must not be forced into the same canonical name, even if their current surface spelling looks similar.
• Do not add prefixes or suffixes such as default_, global_, suite_, or similar markers only because the storage scope changes.
• Canonical names are chosen from runtime semantics, not from storage location.

Placement Rule

• User config shared parameters must live under defaults.
• Scenario-level shared parameters must also live under defaults.
• Suite-level parameters live directly inside each suites[] item.
• CLI flags use the canonical parameter name with dashes (e.g., --ui-host for ui_host).

Examples:

User config (~/.config/zero-qa/config.yaml, only overridden keys needed):

defaults:
  agent_type: codex
  agent_model: gpt-5.4
  run_base_dir: "~/zero-qa-runs"
  ui_host: 127.0.0.1
  ui_port: 8555

Scenario-level shared defaults in zero-qa.yaml:

defaults:
  agent_type: codex
  agent_model: gpt-5.4
  executor_type: web-executor

suites:
  - name: smoke
    path: suites/smoke.md

Suite-level override in zero-qa.yaml:

suites:
  - name: smoke
    path: suites/smoke.md
    agent_type: claude_code
    agent_model: sonnet

CLI:

zero-qa run --scenario zero-qa.yaml --agent-type codex --agent-model gpt-5.4 --executor-type web-executor --run-base-dir tmp/zero-qa-runs
zero-qa ui --run-base-dir tmp/zero-qa-runs --ui-host 127.0.0.1 --ui-port 8555

Override Strategy

All parameters follow the same coverage rule:

• The narrower supported scope wins: CLI > suite item > scenario defaults > user config > code defaults.
• Unsupported scopes are skipped instead of participating in resolution.
• A parameter can only be set in scopes that explicitly support it. Putting a parameter into an unsupported scope is not an override mechanism.
• Code defaults and user config together provide shared defaults. They do not own suite structure or business content.
• The scenario file selector can come from CLI or defaults.scenario (user config or code default), but a scenario file does not override its own path.
• Unknown keys in the scenario file should be rejected.
• zero-qa run and zero-qa ui do not share the same resolution surface. The ui command has no scenario context, so its overrides stop at CLI > user config > code defaults.

Shared Parameters

Canonical parameter	Type / Values	Code default	User config	Scenario defaults in zero-qa.yaml	zero-qa.yaml suite	CLI	Description
agent_type	codex | claude_code	codex	Yes	Yes	Yes	Yes	Agent runtime type.
agent_model	String	None	Yes	Yes	Yes	Yes	Agent model passed through to the selected agent CLI.
executor_type	Directory names ending with -executor	None; must be set in scenario defaults or CLI.	No	Yes	No	Yes	Execution target type.
run_base_dir	Path string	${SYSTEM_TEMP_DIR}/zero-qa-runs	Yes	Yes	No	Yes	Base directory for generated run outputs, logs, results, and UI reads. CLI override exists on both zero-qa run and zero-qa ui.
run_dir_ttl	Duration string such as 0, 30s, 10m, 2h, 1d, 1h30m	1d	Yes	Yes	No	Yes	Retention window for the current run directory and sibling run-directory pruning.
host_tools_auto_install	true | false	false (opt-in to avoid unexpected host changes)	Yes	Yes	No	Yes	Whether missing host tools are installed automatically.
scenario	File name or path string	zero-qa.yaml	Yes	No	No	Yes	Scenario file to load.
ui_host	Host string	127.0.0.1	Yes	No	No	Yes	Host used by the local UI server.
ui_port	Integer port	8555	Yes	No	No	Yes	Port used by the local UI server.

Scenario-Only Parameters

Canonical parameter	Type / Values	Default	Description
scenario_name	String	None; must be set explicitly.	Scenario name.
pre_test_scripts	Ordered list	Empty list.	Pre-test script list.
pre_test_scripts.path	Relative path string	None; must be set explicitly.	Pre-test script path.
pre_test_scripts.executor_type	Directory names ending with -executor	Omit unless the script targets one executor type.	Executor type filter for one pre-test script.
post_test_scripts	Ordered list	Empty list.	Post-test script list.
post_test_scripts.path	Relative path string	None; must be set explicitly.	Post-test script path.
post_test_scripts.executor_type	Directory names ending with -executor	Omit unless the script targets one executor type.	Executor type filter for one post-test script.
suites	Non-empty list	None; must be declared explicitly.	Suite list.

Runtime behavior notes for scenario scripts:

• pre_test_scripts run before runtime input resolution and fail fast on the first non-zero exit code.
• post_test_scripts run in finalization after the main run status is decided. They are best-effort: failures are logged as warnings and do not replace PASS or FAILED.
• Both script lists reuse the same relative-path, working-directory, and executor_type filtering rules.
• Run total_duration excludes post_test_scripts and executor post_run_hooks; post_test_scripts_duration is tracked separately in results/summary.json.

Executor-specific variables live under a top-level key matching the executor_type name (not under defaults). Each executor requires different keys:

Executor	Required scenario variables
mobile-executor	mobile_app_package — target mobile app package name.
adb-executor	adb_app_package — target ADB app package name.
web-executor	entry_url — browser entry URL or deep link.

Example:

scenario_name: sample-project
defaults:
  executor_type: mobile-executor
mobile-executor:
  mobile_app_package: com.example.app
adb-executor:
  adb_app_package: com.example.app
web-executor:
  entry_url: https://example.com/login
suites:
  - name: smoke
    path: suites/smoke.md

Suite-Only Parameters

Canonical parameter	Type / Values	Default	Description
suites.name	String	None; must be set explicitly.	Suite name declared in scenario data.
suites.path	Relative path string	None; must be set explicitly.	Suite file path.
suites.needs	List of suite names	Empty list.	Suite dependencies.
suites.agent_type	codex | claude_code	Inherits from shared default.	Agent runtime type for one suite.
suites.agent_model	String	Inherits from shared default.	Agent model override for one suite.

CLI-Only Parameters

Canonical parameter	Type / Values	Default	Description
selected_suites	Zero or more suite names	Omit to run all suites in the scenario.	Suite name list selected for execution.