Skip to main content

api exec

Starts and Optic service locally to receive traffic from middleware integrated with your code, and starts your project. exec allows you to run any project in any environment and capture traffic. It takes the command to start your project as a required parameter.

api run

You can also take the command to start your project and define a task in optic.yml with only a command parameter. This task can be run with api run <taskname> and it will behave just like api exec. Please check out an example

Flags & Options#

Exec has a few flags that can modify the default behavior:

  • -c/--print-coverage prints how much of the documented API is covered by traffic seen in the capture session. The coverage prints once the session is terminated (ctrl+c or when tests finish running).
  • --ci Enables CI-specific behavior. This enables --print-coverage, --exit-on-diff, and pass-exit-code.
  • --exit-on-diff returns an exit code of 1 if unexpected API behavior is returned, such as an undocumented route or a change in behavior on a documented route. Normally, Optic returns 0 on successful termination regardless of the behavior observed. This is primarily used in CI/CD scenarios, such as in GitHub Actions, to fail builds when undocumented behavior is detected.
  • --pass-exit-code returns the exit code of your task. If you are using a dependent task, the exit code of the dependent command (not the base command) will be passed through. This flag is overridden by - - - --verbose which provides extra troubleshooting information at task startup, task end, and when traffic is observed. We recommend using this when configuring a new task.


Run an application with integrated middleware
api exec "cargo run"
Running command: node basic-http-server.jsTraffic can be sent to: http://localhost:3700/

Run a task in optic.yml as an exec command
api run start
optic.yml task for an exec command
name: "todo-js"tasks:  start:    command: node server.js

Issues & Contributing#

Having trouble? Open an issue on GitHub

Have an idea for changing this command? Here's where it lives in the repo. PRs welcome!

Need help or want to talk with us about a use case? Join Contributing on Discord