test

codify test
[--debug]
[-o plain|default|debug|json]
[-S <value>]
[--operatingSystem macOS|linux]

The test command allows you to test your Codify configuration in an isolated virtual machine environment before applying it to your local system. This is particularly useful for validating complex configurations, testing cross-platform compatibility, or experimenting with new resources without affecting your actual machine.

Codify uses Tart VMs to create an isolated testing environment. The command automatically:

1. Validates your configuration file
2. Spins up a clean VM (macOS or Linux)
3. Mounts your Codify configuration with live-reload support
4. Opens a terminal in the VM to run codify apply

Changes to your local codify.jsonc file are automatically synced to the VM in real-time, allowing you to iterate quickly on your configuration.

Prerequisites

The test command requires:

• macOS host machine (currently the only supported host platform)
• At least 25GB of free disk space for the VM image installation

If Tart is not installed or the required base VM image (codify-test-vm-macos or codify-test-vm-linux) is missing, the test command will automatically install them for you.

Options

Operating System: --operatingSystem -o
Specify the operating system to use for the test VM. Options: macOS or linux. Defaults to your current host operating system.

Debug output mode: --debug
Enable debug mode for verbose logging. The DEBUG=codify flag will be passed to all plugins for detailed troubleshooting output.

How It Works

1. Validation Phase: Your configuration is validated locally before the VM starts to catch any syntax or schema errors early.

2. VM Creation: A temporary VM clone is created from the base image. The VM is automatically deleted when you exit.

3. Bind Mounting: Your Codify installation and configuration directory are mounted into the VM as shared volumes, enabling live changes without copying files.

4. Live Sync: A file watcher monitors your local configuration file. Any changes are automatically reflected in the VM, allowing you to test modifications in real-time.

5. Interactive Testing: A terminal opens in the VM where you can run codify apply and observe the results in the isolated environment.

Use Cases

Test before you apply: Validate that your configuration works as expected without risking your local machine setup.

Cross-platform testing: Test Linux configurations from a macOS host, or vice versa, to ensure your config works across different operating systems.

Experiment safely: Try out new resources, plugins, or configurations in a disposable environment that can be easily reset.

Team validation: Test shared team configurations before distributing them to ensure they work on clean systems.

Examples

# Test on your current OS
codify test

# Test Linux configuration from macOS host
codify test --operatingSystem linux

# Test with debug output
codify test --debug

Workflow Example

# Start testing your configuration
codify test

# The VM starts and opens a terminal
# In the VM terminal, run:
codify apply

# Edit your local codify.jsonc file
# Changes sync automatically to the VM
# Run codify apply again in the VM to test the changes

# Exit the VM terminal when done
# The VM is automatically deleted

Notes

• The VM runs in the foreground. You must manually exit the VM GUI/terminal to stop the test and delete the VM.
• The base VM images (codify-test-vm-macos and codify-test-vm-linux) must be set up beforehand using Tart.
• Configuration files are mounted read-only to prevent accidental modifications from within the VM.
• Each test creates a unique VM clone to ensure test isolation.