Skip to content

Testing with Kubiya CLI

This guide explains how to use the Kubiya CLI to test tools built with the Kubiya SDK. The CLI provides capabilities to verify that your tools work as expected before they're used in production environments.

Prerequisites

Before you begin, make sure you have:

  1. Installed the Kubiya CLI
  2. Set up authentication with your Kubiya environment
  3. Added at least one source containing tools (see Managing Sources)
  4. Familiarized yourself with tool management (see Managing Tools)

Testing Individual Tools

The primary way to test tools with the Kubiya CLI is through the tool test command:

Bash
kubiya tool test TOOL_ID --param key1=value1 --param key2=value2

For example, to test a deployment tool:

Bash
kubiya tool test deploy-app --param namespace=staging --param version=1.2.3

Interactive Mode

You can also test tools in interactive mode, which will prompt you for each parameter:

Bash
kubiya tool test TOOL_ID --interactive

Testing from Specific Sources

If you have multiple sources with the same tool ID, you can specify the source:

Bash
kubiya tool test TOOL_ID --source SOURCE_ID --param key=value

Working with Environment Variables

Many tools require environment variables. To use them with the tool test command:

Bash
export API_KEY=your-api-key
export AWS_SECRET=your-secret
kubiya tool test tool-requiring-secrets

Validating Tool Definitions

Before testing, you can validate tool definitions to ensure they're properly structured:

Bash
kubiya source validate .

This checks all tool definitions in the current directory for structural validity and required fields.

Debugging Tool Execution

To help debug issues with tool execution, you can use verbose mode:

Bash
kubiya tool test TOOL_ID --verbose

This will provide more detailed output about the tool's execution, including: - Parameter validation - Docker container setup - Tool execution steps - Error details

Checking Tool Logs

After running a tool, you can check its logs:

Bash
kubiya tool logs TOOL_ID

If you're testing a specific run of a tool:

Bash
kubiya tool logs TOOL_ID --run-id RUN_ID

Docker Container Inspection

Since tools run in Docker containers, you can inspect the underlying containers:

Bash
kubiya container list

To see logs from a specific container:

Bash
kubiya container logs CONTAINER_ID

Best Practices for Testing

  1. Test in development first: Always test tools in development before deploying to production.

  2. Use realistic data: Test with data that closely resembles your production data.

  3. Test with correct permissions: Ensure the CLI has the same permissions as would be used in production.

  4. Version your tools: Keep tool definitions under version control and test specific versions.

  5. Document test cases: Maintain documentation of test cases for each tool.

Troubleshooting

Tool Not Found

If you encounter a "Tool not found" error:

  • Verify the tool ID is correct
  • Check if the tool exists with kubiya tool list
  • Ensure the source containing the tool is properly synced

Parameter Validation Errors

If parameters fail validation:

  • Check the parameter types match the tool's expectations
  • Verify required parameters are provided
  • Ensure enum parameters have valid values

Runtime Errors

If a tool fails during execution:

  • Check that any required environment variables are set
  • Verify external services the tool depends on are accessible
  • Look for specific error messages in the tool output
  • Use kubiya container logs to view detailed logs

Next Steps

Now that you know how to test tools, learn how to: