Skip to content
Rival Docs

Testing & Executing

Testing on Rival means running your tool with a real input - not a simulation. When you execute a test in the builder, your code actually runs, consumes credits, and returns a real response. This gives you confidence that what you publish works the way you expect before anyone else can call it.

Where testing happens

Testing takes place in Step 3 - Code & Test of the tool builder. This step gives you a split view: your code editor on one side, and an execution panel on the other. You write or paste your handler, define the input using an event, and run it directly from the browser.

This is the primary place to develop and validate your tool before it reaches the publish step.

Events and test cases

An event is a named, structured input payload saved on a specific version of your tool. When you define an event, you’re describing a set of inputs that represents a real scenario - for example, a request to summarize a piece of text, or to look up a user by ID.

A test case is an event that you’ve run and saved as a runnable example. To create one, define the input payload in the event editor, execute it, and confirm the result. Once you have a passing execution saved as a test case, it acts as a baseline that proves your tool works end to end.

Rival requires at least one passing test case before a tool can be published. This is a hard requirement, not a suggestion - the publish step will not proceed until it is met.

Running your tool from the marketplace

Once a tool is published, authenticated users can execute it directly from its detail page on the marketplace at cortexone.rival.io - no code required. They fill in the input fields defined by your event schema and trigger the execution from the browser. The response is displayed inline.

This makes your tool immediately accessible to non-technical users who don’t need or want to call the API directly. It also lets you share a link to your tool and have someone test it in seconds.

Execution logs

Every execution - whether triggered from the builder, the marketplace, or the API - is logged. The log entry captures:

  • The tool and version that ran
  • The input payload (event)
  • The full output response
  • The number of credits consumed
  • Whether the execution succeeded or failed

You can review execution history from the executions panel in the Dashboard dashboard. Use this to track usage patterns, spot recurring failures, and understand what inputs callers are actually sending.

Debugging

When an execution fails, the log entry is your first stop. Look at the output body - it will usually contain an error message from your handler or a platform-level error code.

If your handler threw an unhandled exception, the response will have a statusCode of 500 and the body will contain the error message from the runtime. If the error is coming from your own validation logic, the status code will be whatever your handler returned.

Common things to check when a run fails:

  • Does the input payload match the schema your handler expects? Missing required fields are a frequent source of errors.
  • Are environment variables assigned to the tool? If your code reads a variable that wasn’t assigned, it silently receives a null value.
  • Is the error coming from an external API call? Check whether credentials are valid and whether the service is reachable.

For a full list of error codes and what they mean, see the Error Reference.

Builder testing vs. production execution

There is no functional difference between a test execution in the builder and a production execution via the API or marketplace - the same code runs on the same infrastructure. The distinction is contextual:

Builder testing is where you iterate while building. You control the inputs, inspect every output, and can make changes to the code between runs. It’s a development loop.

Production execution is what happens after publishing. Callers send inputs through the API or marketplace, and your published, immutable version handles the request. You observe the results through execution logs rather than watching them in real time.

This means that if it passes in the builder, it will behave the same way in production - as long as the inputs are equivalent.