1.1 Generate Command

To create a contract test for an endpoint, specify the endpoint you want to test. In this example, we are using the https://demoshop.skyramp.dev/api/v1/products as the URL to our service. When testing your service, replace it with the URL to the endpoint you want to test.

skyramp generate contract rest https://www.skyramp.dev/api/v1/products \
--language python \
--framework pytest \
--api-schema openapi.json

This command generates a contract test file: products_contract_test.py.

1.2 Execute Contract Test

You can execute the generated tests without any additional adjustments to the code. In a later section, we will elaborate on how to make changes to the code, if needed.

1.2.1 Set env variable for authentication (if needed)

Skyramp’s sample application (link) doesn't require authentication, however, as most applications do, you can quickly pass your token via an environment variable. By default, Skyramp expects a Bearer Token but we support additional authentication methods.

export SKYRAMP_TEST_TOKEN=$your_auth_token

1.2.2 Run the test

Run the tests using Pytest. If you don’t have Pytest, install it with pip by running the following command in your terminal:

# Prerequisites 
pip install pytest

# Execution of contract test for products/POST 
python3 -m pytest products_contract_test.py

1.2.3 Results

We are using Pytest’s default test output in this guide, printing a line for each test that is being run and listing all failures at the end. You can adjust the output behavior following this documentation.

We can see that the test checks 5 methods that all test cases pass.

SCREENSHOT

2. Customize Test Generation

2.1 Generation from Request Data

Instead of using your API spec, Skyramp enables users to also generate contract tests based on sample request and response data. This allows users to quickly test specific scenarios that depend on specific data. This is currently only possible if a method is specified.

request.json

{
    "category": "toys",
    "description": "bear",
    "image_url": "picture",
    "in_stock": false,
    "name": "bigbear",
    "price": 10
}

response.json

{
  "category": "toys",
  "created_at": "2025-02-25T10:54:22-05:00",
  "description": "bear",
  "image_url": "picture",
  "in_stock": false,
  "name": "bigbear",
  "price": 10,
  "product_id": 0
}

Generate Command

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--request-data @request.json \
--response-data @response.json

2.2 Test generation for Robot framework

Next to Pytest, Skyramp also supports the Robot framework in Python.

Generate Command

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework robot \
--api-schema openapi.json

This command generates two files:

• products_contract_test.py

• products_contract_test.robot (simple Robot wrapper file)

Execute Test

Ensure that authentication is properly set up. We now run the test using the Robot Framework. You can call the generated Python file either in an existing robot file of yours or leverage the simple wrapper file we generate.

# Prerequisites
pip install robotframework

# Execution of contract test for products/POST 
python3 -m robot products_contract_test.robot

The results will be outputted following the typical stdout from Robot. You can find more information on the generated outputs in the Robot documentation.

2.3 Specification of form parameters for POST request

For POST requests, you can also provide form params instead of an API schema or sample request data.

Generate Command

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--form-params category=toys \
--form-params description=bear \
--form-params image_url=picture \
--form-params in_stock=false \
--form-params name=bigbear \
--form-params price=10 \
--response-data @response.json

2.4 Definition of expected response status code

By default, Skyramp assumes the expected status code to be 20X. You can quickly change this by specifying the expected status code in the flags.

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--response-status-code 40X \
--api-schema openapi.json

2.5 Change of authentication type

By default, Skyramp assumes a Bearer token. You can define the key of your authentication header with the auth-header flag.

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--auth-header X-API-KEY \
--api-schema openapi.json

2.6 Specification of path parameters for a single method

You can easily define the relevant path param for your requests by leveraging the path-param flag. It will override the path parameter in the path with the value you provide.

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products/{product_id} \
-X PUT \
--language python \
--framework pytest \
--path-params product_id=2 \
--api-schema openapi.json

2.7 Specification of path parameters for entire endpoints

You can also specify path params if you test an entire endpoint. Skyramp overrides the path param value for all methods that have a path parameter in the path with the value you specify.

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products/{product_id} \
--language python \
--framework pytest \
--path-params product_id=2 \
--api-schema openapi.json

2.8 Specification of query parameters

You can provide specific query parameters to the generation command to ensure your expected outcome. This is only possible when specifying a single method.

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X GET \
--language python \
--framework pytest \
--query-params limit=5 \
--query-params order=desc \
--api-schema openapi.json

2.9 Change of test runtime to Docker

Instead of using “local” execution, Skyramp also supports seamless support for testing applications in your docker network.

api-sample is the service alias; repalce with your service name

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--runtime docker \
--docker-network api-insight_default \
--docker-skyramp-port 35142 \
--api-schema openapi.json

2.10 Definition of test name and location

The additional flags allow you to specify the directory and file name of the generated test.

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--api-schema openapi.json \
--output post_products_contract_test.py \
--output-dir skyramp_tests

2.11 Force overwrite of test files

If you are overwriting the file you can force it with this flag

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--api-schema openapi.json \
--overwrite

2.12 Deployment of Skyramp Dashboard

The Skyramp Dashboard allows you to collect and see the test results. It requires Docker as it is deployed on a Docker network to collect and store the test results.

If you execute this test, Skyramp will automatically download the required components and deploy the Skyramp Dashboard on Docker. The Dashboard is available under http://localhost:3000/tests.

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--api-schema openapi.json \
--deploy-dashboard

2.13 Change of body value asserts

The assert flag allows you to specify how the generated code asserts the body values of the response. By default, Skyramp generates value asserts for the first 3 body values. You can choose to generate asserts for all body values (--asserts all) or no values at all (--asserts none).

skyramp generate contract rest https://demoshop.skyramp.dev/api/v1/products \
-X POST \
--language python \
--framework pytest \
--api-schema openapi.json \
--asserts all