Capturing Test Traffic

Capturing Traffic

Optic Capture helps create OpenAPI specifications and keep them up to date by examining the traffic to your API. Under the hood the following happens when running Capture,

  • Your API is started via a command you provide.
  • A reverse proxy is configured to send traffic to your API.
  • A command or set of requests you provide is run, generating traffic to the proxy.
  • Optic observes the traffic as it passes through the proxy.
  • These observations can then be used to create or update your OpenAPI specification.

By default, all of this happens locally. Your capture details and API specification are not sent to Optic unless you explicitly opt into uploading your results to Optic Cloud.

You can view the capture CLI options with,

optic capture --help


Capture is configured inside your optic.yml file. Whether or not you already have an optic.yml, getting started is easy via the optic capture init command.

You can insert a configuration block into your optic.yml (generating one if necessary) with a complete, commented configuration example:

optic capture init [./path/to/your/]openapi.yml

Configuration Reference

optic capture init can also display a capture configuration example with the --stdout argument, making it a useful starting point. For more advanced use, here is a feature-complete Capture configuration example.

      # The command to run your server.
      # Optional: If omitted, Optic assumes the server is running or started elsewhere.
      command: your-server-command
      # The url where your server can be reached once running.
      # Required: Can be overridden with '--server-override'.
      url: http://localhost:8080
      # A readiness endpoint for Optic to validate before sending requests.
      # Optional: If omitted, perform no readiness checking.
      ready_endpoint: /
      # The interval to check 'ready_endpoint', in ms.
      # Optional: default: 1000
      ready_interval: 1000
      # The length of time in ms to wait for a successful ready check to occur.
      # Optional: default: 10_000, 10 seconds
      ready_timeout: 10_000
    # One of '' or 'requests.send' is required.
      # Run an external command to generate traffic.
        # The command to run to generate traffic (e.g., your test command, etc.).
        command: your-test-command
        # The name of the environment variable injected into the env of 'command' that contains the address of the Optic proxy.
        # Optional: default: OPTIC_PROXY
        proxy_variable: OPTIC_PROXY
      # Use Optic to generate requests.
        - path: /users/create # Required
          method: POST # Optional: default: GET
          headers: # Optional
            content-type: application/json;charset=UTF-8 # If omitted, this is the default
          data: # Optional: If omitted on a POST request, default: {}
            name: Hank
      # The number of parallel requests to make when using 'requests.send'.
      # Optional: default: 4
      request_concurrency: 4

Once you've set up your capture configuration you're ready to update, create, and verify your OpenAPI spec!

Create/Update an OpenAPI spec

You can persist changes to (or create) your OpenAPI spec by including --update <mode> in your capture command.

 optic capture openapi.yml --update automatic
Initializing OpenAPI file at openapi.yml
 Successfully captured requests
Learning path patterns for unmatched requests...
Documenting new operations:
 GET /
 GET /users
 POST /users/create

There are 3 update modes,

interactiveInteractively prompt and confirm observed changes to new and existing endpoints.
automaticAutomatically apply observed changes to new and existing endpoints.
documentedAutomatically apply observed changes to existing endpoints only.

Verify an OpenAPI spec

If you already have an OpenAPI spec and run capture without the --update <mode> option, the requests observed will be compared against your spec without making changes to it.

$ optic capture openapi.yml
 Successfully captured requests
 GET /
  200 response
  [404 response body] body is not documented
 GET /users
   200 response
 POST /users/create
   Request Body,  201 response

Next Steps

View examples generating traffic to Optic, or import existing requests from HAR files or Postman collections.