Skip to content

TofuSoup Configuration (soup.toml)

TofuSoup uses a TOML file named soup.toml for configuration. This file allows users to customize default behaviors for various commands, harness settings, and test execution parameters.

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Location

TofuSoup searches for soup.toml in the following order: 1. Path specified by the global --config-file <path> CLI option. 2. ./soup.toml (in the current working directory). 3. <project_root>/soup/soup.toml (recommended default location).

If no configuration file is found, TofuSoup operates with built-in defaults.

Precedence

For settings that can be defined in multiple places, the following order of precedence applies (highest to lowest): 1. Command-line arguments. 2. Environment variables (e.g., TOFUSOUP_LOG_LEVEL). 3. Settings in soup.toml. 4. Hardcoded application defaults.

Top-Level Tables

[global_settings]

Settings that apply across the TofuSoup application.

  • default_python_log_level (String): Sets the default logging level for TofuSoup's own Python-based logging. Valid values: "TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL".
  • default_harness_log_level (String): A general default log level for external Go harnesses. Valid values for Go harnesses: "TRACE", "DEBUG", "INFO", "WARN", "ERROR".

[harness_defaults.<language>]

Provides default settings for all harnesses of a specific language (e.g., [harness_defaults.go]).

  • build_flags (Array of Strings): Default flags passed to go build.
  • common_env_vars (Table): Environment variables to set for all Go harness operations.
  • default_log_level (String): Default log level specifically for Go harnesses.
  • timeout_seconds (Integer): Default timeout for running Go harness commands.

[harness.<language>."<component_id>"]

Specific settings for an individual harness, overriding language defaults. Example: [harness.go.cty].

  • build_flags, custom_env_vars, log_level, timeout_seconds.

[command_options."<command_group>.<command_name>"]

Provides default values for specific CLI command options.

Example: 

[command_options."hcl.convert"]
default_output_format = "json"

[test_suite_defaults]

Default settings applicable to all test suites run via soup test.

  • env_vars (Table): Environment variables to set for all test runs.
  • extra_pytest_args (Array of Strings): Additional arguments always passed to pytest.
  • skip_tests (Array of Strings): Test items to skip.

[test_suite.<suite_name>]

Specific settings for a named test suite (e.g., [test_suite.rpc]), overriding defaults.

  • env_vars, extra_pytest_args, skip_tests.

[workenv]

Configuration for tool management, powered by wrkenv. When configured in soup.toml, these settings are injected into wrkenv, making wrkenv.toml optional.

  • terraform_flavor (String): Default terraform flavor - "terraform" or "opentofu"
  • tools (Table): Tool versions to use (e.g., terraform = "1.5.7")
  • settings (Table): Various settings like verify_checksums and cache_downloads

[workenv.matrix]

Configuration for matrix testing with soup stir --matrix.

  • versions (Table): Additional versions to test for each tool
  • parallel_jobs (Integer): Number of parallel test jobs (default: 4)
  • timeout_minutes (Integer): Timeout for each test run (default: 30)

Example: 

[workenv]
terraform_flavor = "opentofu"

[workenv.tools]
terraform = "1.8.5"
tofu = "1.10.5"

[workenv.settings]
verify_checksums = true
cache_downloads = true

[workenv.matrix]
parallel_jobs = 8
timeout_minutes = 45

[workenv.matrix.versions]
terraform = ["1.5.7", "1.6.0", "1.6.1"]
tofu = ["1.6.2", "1.7.0", "1.8.0"]

Note: You can alternatively configure wrkenv using a wrkenv.toml file. Settings in soup.toml take precedence over wrkenv.toml.