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

This command generates one file:

• products_contract_test.py.

Explanation of Command

• https://demoshop.skyramp.dev/api/v1/products: Defines the URL to the endpoint we aim to test.

• NOTE: No API method is specified in this generation command. When paired with an OpenAPI spec, Skyramp will generate tests for all endpoints at the URL, its direct parent (if any), and its direct children.

• --language: Specifies the test output language. For contract testing, we currently support Python, Typescript, and Java.

• --framework: Specify the test execution framework of choice.

• --api-schema: Points to the OpenAPI schema used to generate the test. We also support sample data as an input for contract test generation.

Adjustments

These flags customize the test generation. Additional flags are explained here.

• --asserts: An assert is a way to tell Skyramp what return values the test should check for. Skyramp evaluates the endpoint to determine what values are expected, and then the test checks to see whether they are returned. For more information about asserts, see the Examples page.

  • Specifying all will return an assertion for every API response key available in the endpoint.

  • Specifying none will not return any assertions.

  • You can also specify the number of return values you wish. The default is 3, which will return the HTTP response code and the first three response body values that occur after that.

• --response-status-code: Specify the expected status code. By default, Skyramp either asserts against the defined status code in the API specification or defaults to 20X.

• --output: Specify the name of the generated test file.

• --output-dir: Specify the directory to store the generated test file.

Execute the Contract Test

You can execute the generated tests without any additional adjustments to the code. However, based on the application you want to test, you can pass your authentication token to Skyramp Tests via an environment variable.

Set environment variable for authentication (if applicable)

Skyramp’s sample application doesn't require any authentication.

Ensure proper authentication for test execution. To test against an application that does require authentication, pass your token using an environment variable. By default, Skyramp expects a Bearer Token but we support additional authentication methods. If your API does not require any authentication, you can skip this step and just run the test.

export SKYRAMP_TEST_TOKEN=$your_auth_token

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 
pip3 install pytest

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

Review Test Results

We are using Pytest’s shortened traceback (--tb=short) 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.

Test failure

We can see that the test checks 5 methods that only 2 test cases pass. This is because the failing endpoints are attempting to read/update/delete a product ID 0 that does not exist in the application’s database.

Successful test

To make this contract test succeed, we will need to create a product at the beginning of each failing test case. The created product’s product_id should then be used as the product_id path parameter for each failing request. This change is to ensure without exception that the test case will operate against an existing product.

Here are the specific steps (in order) to fix this contract test:

1. Create a helper function for making the POST request. Add the following code block to line 21:

# Helper function to execute POST request
def execute_POST_request():
    # Invocation of Skyramp Client and calling of authentication header
    client = skyramp.Client()
    headers = get_header()

    # Request Body
    products_POST_request_body = r'''{
            "category": "Toys",
            "description": "Bear Soft Toy",
            "image_url": "https://images.app.goo.gl/cgcHpeehRdu5osot8",
            "in_stock": true,
            "name": "bigbear",
            "price": 9.99
        }'''

    # Execute Request
    products_POST_response = client.send_request(
        url=URL,
        path="/api/v1/products",
        method="POST",
        body=products_POST_request_body,
        headers=headers
    )
    return products_POST_response

2. Update your failing test cases to call execute_POST_request and use the product_id. Interpolate the product_id into your expected response for each test case.

• test_products_product_id_get - replace lines 136-150 with the following code block:

# Declaration of variables
product_id = skyramp.get_response_value(execute_POST_request(), "product_id")

# Expected Response Body
expected_products_product_id_GET_response_body = f'''{{
        "category": "Toys",
        "created_at": "2025-02-25T10:54:22-05:00",
        "description": "Bear Soft Toy",
        "image_url": "https://images.app.goo.gl/cgcHpeehRdu5osot8",
        "in_stock": true,
        "name": "bigbear",
        "price": 9.99,
        "product_id": {product_id},
        "updated_at": "2025-02-25T10:54:22-05:00"
    }}'''

• test_products_product_id_put - replace lines 173 - 197 with the following code block:

# Declaration of variables
product_id = skyramp.get_response_value(execute_POST_request(), "product_id")

# Request Body
products_product_id_PUT_request_body = r'''{
        "category": "Toys",
        "description": "Bear Soft Toy",
        "image_url": "https://images.app.goo.gl/cgcHpeehRdu5osot8",
        "in_stock": true,
        "name": "bigbear",
        "price": 9.99
    }'''

# Expected Response Body
expected_products_product_id_PUT_response_body = f'''{{
        "category": "Toys",
        "created_at": "2025-02-25T10:54:22-05:00",
        "description": "Bear Soft Toy",
        "image_url": "https://images.app.goo.gl/cgcHpeehRdu5osot8",
        "in_stock": true,
        "name": "bigbear",
        "price": 9.99,
        "product_id": {product_id},
        "updated_at": "2025-02-25T10:54:22-05:00"
    }}'''

• test_products_product_id_delete - replace lines 222 with the following line:

product_id = skyramp.get_response_value(execute_POST_request(), "product_id")

• (Optional) You can also update test_products_post to use this helper function for cleaner code, but we will not show it here as it is not strictly required.

This results in a successful test run where all 5 cases pass. The expected output looks the following:

Next Steps

Congratulations! You have successfully generated a full suite of contract tests for a REST endpoint. You can adjust the asserts directly in the output file (see Test File Anatomy link for an example with a single method).

Related topics

• Contract Test File Anatomy

• Skyramp Demo Shop

• Flags Glossary