Installation¶

Get started with TofuSoup, a cross-language conformance testing suite and tooling framework for OpenTofu/Terraform ecosystems.

Prerequisites¶

Go Required for Test Harnesses

Go 1.21+ is required to build test harnesses for cross-language compatibility testing. If you only need the Python CLI tools without harness building, Go is optional.

Installation Methods¶

As a Command-Line Tool¶

If you want to use the soup CLI for CTY, HCL, wire protocol, and RPC operations:

Using uv (Recommended):

# Install tofusoup globally with uv
uvx soup --help

# Or install in a dedicated virtual environment
uv tool install tofusoup

# With all optional dependencies
uv tool install "tofusoup[all]"

Using pipx (Alternative):

# Install as isolated CLI tool
pipx install tofusoup

# With all features
pipx install "tofusoup[all]"

Using pip:

# Basic installation
pip install tofusoup

# With all optional dependencies
pip install "tofusoup[all]"

As a Library Dependency¶

If you're integrating TofuSoup into your project:

Using uv:

uv add tofusoup

# Or with specific extras
uv add "tofusoup[cty,hcl,rpc]"

In your pyproject.toml:

[project]
dependencies = [
    "tofusoup[all]>=0.1.0",
]

For Development¶

Clone the repository and set up the development environment:

# Clone the repository
git clone https://github.com/provide-io/tofusoup.git
cd tofusoup

# Set up development environment
uv sync

# Or install with all development dependencies
uv sync --all-groups

# Verify installation
soup --version

This creates a .venv/ virtual environment with all dependencies installed.

Optional Dependencies¶

TofuSoup has several optional dependency groups for specific features:

CTY Support¶

pip install "tofusoup[cty]"

Includes: - pyvider-cty - Python implementation of go-cty type system - CTY value operations and conversions - Type-safe value creation and manipulation

CLI Commands:

soup cty view data.json
soup cty convert input.json output.msgpack

HCL Support¶

pip install "tofusoup[hcl]"

Includes: - pyvider-hcl - Python HCL parser - HCL to JSON/CTY conversion - Configuration parsing

CLI Commands:

soup hcl parse config.hcl
soup hcl to-json config.hcl output.json

RPC Support¶

pip install "tofusoup[rpc]"

Includes: - pyvider-rpcplugin - RPC plugin infrastructure - gRPC server and client implementations - Plugin protocol support

CLI Commands:

soup rpc kv server-start
soup rpc kv put key value
soup rpc kv get key

Browser/TUI Support¶

The interactive Terminal UI (sui command) requires additional dependencies:

pip install "tofusoup[browser]"

Features: - Interactive registry browser - Provider and module exploration - Rich terminal interface

CLI Commands:

sui  # Launch interactive browser

Matrix Testing¶

Matrix testing across multiple Terraform/OpenTofu versions requires wrknv:

# Install from local source (not yet on PyPI)
pip install -e /path/to/wrknv

Features: - Multi-version testing - Parallel test execution - Version management integration

All Features¶

Install all optional dependencies at once:

pip install "tofusoup[all]"

Includes: cty, hcl, rpc, and browser support.

Note: Matrix testing (wrknv) requires separate installation as it's not on PyPI yet.

Building Test Harnesses¶

TofuSoup uses Go test harnesses for cross-language compatibility testing:

Unified Go Harness (soup-go)¶

The recommended harness for all cross-language testing:

# List available harnesses
soup harness list

# Build soup-go harness
soup harness build soup-go

# Verify harness CLI
soup harness verify-cli soup-go

Build Artifacts: - Harness binaries: harnesses/bin/ - Not included in version control - Must be built locally

Using Harnesses¶

Once built, harnesses can be used directly:

# Run harness commands
./harnesses/bin/soup-go cty view data.json
./harnesses/bin/soup-go wire encode value.json output.tfw.b64
./harnesses/bin/soup-go hcl parse config.hcl

Harness Features: - Reference implementations in Go - Cross-language compatibility testing - MessagePack and wire protocol support - CTY and HCL operations

Build Requirements¶

Harness building requires:

# Verify Go installation
go version  # Should show 1.21+

# Check GOPATH
go env GOPATH

# Build all harnesses
soup harness build --all

# Clean harness artifacts
soup harness clean

Verifying Installation¶

Basic Verification¶

1. Check Python and Package:

# Check Python version
python --version  # Should show 3.11+

# Verify package installation
python -c "import tofusoup; print('✅ TofuSoup installed')"

# Check version
soup --version

2. Verify CLI Commands:

# Display main help
soup --help

# List available commands
soup cty --help
soup hcl --help
soup wire --help
soup rpc --help

3. Test Core Functionality:

# Test CTY operations (if cty extra installed)
echo '{"type":"string","value":"hello"}' > test.json
soup cty view test.json
rm test.json

# Test harness operations (if Go harness built)
soup harness list

TofuSoup-Specific Verification¶

1. Test Ecosystem Imports:

# Verify pyvider ecosystem integration
from pyvider.cty import CtyString, CtyNumber
from pyvider.hcl import parse_hcl
from pyvider.rpcplugin import plugin_server

# Test TofuSoup modules
from tofusoup.cty import logic as cty_logic
from tofusoup.hcl import operations as hcl_ops
from tofusoup.rpc import services
from tofusoup.testing import runner

print("✅ All imports successful")

2. Run Conformance Tests:

# Run CTY conformance tests
soup test cty

# Run HCL conformance tests
soup test hcl

# Run wire protocol tests
soup test wire

# Run RPC cross-language tests
soup test rpc

3. Test Harness Integration:

# Verify harness is functional
soup harness verify-cli soup-go

# Run harness-based tests
uv run pytest conformance/cty/ -v

Development Workflow¶

Additional Testing Options:

# Run conformance tests
uv run pytest conformance/

# Run with specific markers
uv run pytest -m cty
uv run pytest -m hcl
uv run pytest -m wire

# Run tests in parallel
uv run pytest -n auto

# Run specific test suite via CLI
soup test cty
soup test rpc

Pre-commit Hooks¶

# Install pre-commit hooks
pre-commit install

# Run all hooks manually
pre-commit run --all-files

Building the Package¶

# Build distribution packages
uv build

# The wheel will be in dist/
ls dist/

Configuration¶

TofuSoup can be configured via soup.toml in your project directory:

[global_settings]
default_python_log_level = "INFO"

[harness_defaults.go]
build_flags = ["-v"]
timeout_seconds = 300

[test_suites.cty]
test_dir = "conformance/cty"
markers = ["cty"]

[test_suites.rpc]
test_dir = "conformance/rpc"
markers = ["rpc", "cross_language"]

See Configuration Reference for complete details.

Troubleshooting¶

TofuSoup-Specific Issues¶

Command not found: soup¶

Ensure the package is installed and your PATH includes Python's bin directory:

# Check installation
pip list | grep tofusoup

# Find soup executable
which soup

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

# For virtual environment
source .venv/bin/activate

Go harness build failures¶

Verify Go installation and configuration:

# Check Go installation
go version

# Check GOPATH
go env GOPATH

# Verify Go module support
go env GO111MODULE  # Should show 'on' or ''

# Clean and rebuild
soup harness clean
soup harness build soup-go

Module import errors for pyvider packages¶

Install required optional dependencies:

# Install all extras
pip install "tofusoup[all]"

# Or specific extras
pip install "tofusoup[cty,hcl,rpc]"

# Verify pyvider packages
pip list | grep pyvider

Conformance test failures¶

Ensure harnesses are built and functional:

# Build harness
soup harness build soup-go

# Verify harness CLI
soup harness verify-cli soup-go

# Run with verbose output
uv run pytest conformance/ -vv

# Check for missing test fixtures
ls conformance/fixtures/

RPC plugin connection timeouts¶

Check certificate generation and mTLS setup:

# Verify RPC components
python -c "from pyvider.rpcplugin import plugin_server; print('✅ RPC available')"

# Test basic RPC server
soup rpc kv server-start

# Check logs for certificate errors
export FOUNDATION_LOG_LEVEL=DEBUG
soup rpc kv server-start

Getting Help¶

If you encounter issues:

Check logs - Run with FOUNDATION_LOG_LEVEL=DEBUG for detailed output
Verify Python version - Ensure you're using Python 3.11+
Check optional dependencies - Install required extras for your use case
Verify harnesses - Ensure Go harnesses build successfully
Review configuration - Check soup.toml syntax
Report issues - GitHub Issues

Next Steps¶

Quick Start¶

Quick Start Guide - Run your first TofuSoup commands
What is TofuSoup? - Learn about capabilities and use cases
Configuration Reference - Complete configuration guide

Core Features¶

CTY Operations - Working with Terraform's type system
Wire Protocol - Encoding and decoding wire protocol messages
Matrix Testing - Testing across Terraform/OpenTofu versions
RPC Testing - Cross-language RPC compatibility

Advanced Topics¶

Harness Development - Creating custom test harnesses
Conformance Testing - Testing strategy and patterns
Architecture - System architecture and design

Ready to start testing? Check out the Quick Start Guide!