OpenAPI Data in Tests
The definition of each operation determines what data is used in generated testing. In addition to the data type system shaping data, OpenAPI Specification supports examples. Test generation automatically uses defined examples when available. In the absence of defined examples, test generation attempts to use a realistic example based on the type
, format
(if set), and property name (if applicable).
Example Property
By default, a single test is created based on any example
properties found throughout any defined operation parameters
, requestBody
, and responses
.
Consider the below example. The generator traverses the OpenAPI document to create a single test for the updatePet
operation with id
, name
, and photoUrls
data:
paths:"/pet":put:tags:- petsummary: Update an existing petdescription: Update an existing pet by IdoperationId: updatePetrequestBody:description: Update an existent pet in the storecontent:application/json:schema:"$ref": "#/components/schemas/Pet"required: trueresponses:'200':description: Successful operationcontent:application/json:schema:"$ref": "#/components/schemas/Pet"components:schemas:Pet:required:- name- photoUrlstype: objectproperties:id:type: integerformat: int64example: 10name:type: stringexample: doggiecategory:"$ref": "#/components/schemas/Category"photoUrls:type: arrayitems:type: stringtags:type: arrayitems:"$ref": "#/components/schemas/Tag"status:type: stringdescription: pet status in the storeenum:- available- pending- sold
Here’s how the generator parses this example document:
paths[/pet].put.updatePet
- The test uses theupdatePet
operationId in the test name.paths[/pet].put.requestBody
- The test uses thePet
shared component for both the constructed request body and response object.components.schemas.Pet.required
- ThePet
shared component is an object type with requiredname
andphotoUrls
properties.components.schemas.Pet.id
- While not required, thePet
objectid
property has anexample
property, which is automatically included in the test.components.schemas.Pet.name
- The requiredPet
objectname
property has anexample
property, which is included in the test.components.schemas.Pet.photoUrls
- The requiredPet
objectphotoUrls
property does not include anexample
property, however it has an example value automatically created since it is required.
This definition creates a test with Pet
object request body and response data:
id: 10name: doggiephotoUrls:- <value>
Examples Property
Multiple tests for an operation can be defined using the examples
property, which in this context is a mapping of example name string keys to example values. Prevent missing or mismatched test generation by ensuring the same example name key is used across all necessary parameters
, requestBody
, and responses
parts of the operation. If desired, define reusable examples under components similar to schemas.
In this example, multiple tests (fido
and rover
) are created for the addPet
operation:
paths:"/pet":post:tags:- petsummary: Add a new pet to the storedescription: Add a new pet to the storeoperationId: addPetrequestBody:description: Create a new pet in the storecontent:application/json:schema:"$ref": "#/components/schemas/Pet"examples:fido:summary: fido requestdescription: fido example requestBody for test generationvalue:name: FidophotoUrls:- https://www.example.com/fido.jpgstatus: availablerover:summary: rover requestdescription: rover example requestBody for test generationvalue:name: RoverphotoUrls:- https://www.example.com/rover1.jpg- https://www.example.com/rover2.jpgstatus: pendingrequired: trueresponses:'200':description: Successful operationcontent:application/json:schema:"$ref": "#/components/schemas/Pet"examples:fido:summary: fido responsedescription: fido example response for test generationvalue:id: 1name: FidophotoUrls:- https://www.example.com/fido.jpgstatus: availablerover:summary: rover responsedescription: rover example response for test generationvalue:id: 2name: RoverphotoUrls:- https://www.example.com/rover1.jpg- https://www.example.com/rover2.jpgstatus: pending
Ignoring Data
Data properties can be explicitly ignored in testing via the x-speakeasy-test-ignore
annotation.
In this example, the other
property is omitted from test generation:
paths:/example:get:# ... other operation configuration ...responses:"200":description: OKcontent:application/json:schema:type: objectproperties:data:type: stringother:type: stringx-speakeasy-test-ignore: true