Best Practices

Passing package arguments to the CLI

Passing package parameters via the CLI can get hairy due to the interaction between Bash and JSON quotes. The following are tips to make your life easier:

1. When you have a small number of arguments: surround the arguments with single quotes so you don't have to escape double quotes in your JSON. E.g.:

   kurtosis run github.com/user/repo '{"some_param":5,"some_other_param":"My value"}'
2. When you have a large number of arguments: put them in a .json file and use Bash command substitution inside double quotes to slot them into the kurtosis run command. E.g.:

   kurtosis run github.com/user/repo "$(cat my-params.json)"
   The double quotes around the $(cat my-params.json) are important so any spaces inside my-params.json don't fool Bash into thinking you're passing in two separate arguments.

Choosing the right wait

Kurtosis has three different types of waits. Described here are the three, with tips on when to use each:

1. Automatic waiting on port availability when a service starts (enabled by default; can be configured with PortSpec.wait)
   • Should be sufficient for most usecases
   • Requires little-to-no extra configuration
   • Will cause parallel Plan.add_services to fail, allowing for quick aborting
2. Waiting on ReadyConditions (configured in ServiceConfig)
   • Allows for more advanced checking (e.g. require a certain HTTP response body, ensure a CLI call returns success, etc.)
   • More complex to configure
   • Will cause parallel Plan.add_services to fail, allowing for quick aborting
3. The Plan.wait
   • Most useful for asserting the system has reached a desired state in tests (e.g. wait until data shows up after loading)
   • More complex to configure
   • Cannot be used to short-circuit Plan.add_services

Choosing service names in Kurtosis

Kurtosis service names implements RFC-1035, meaning the names of all services must be a valid RFC-1035 Label Name. Tactically this means a service name must:

• contain at most 63 characters
• contain only lowercase alphanumeric characters or '-'
• start with an alphabetic character
• end with an alphanumeric character

Failure to adhere to the above standards will result in errors when running Kurtosis.