Syncing makes it easy to keep your Assertible tests up-to-date with the latest changes in OpenAPI, Swagger, and Postman API specification documents.
For teams that maintain API definitions in OpenAPI, Swagger, or Postman collection format, a pain-point is often keeping tests up-to-date with the latest changes in the spec. To solve this problem, we've implemented sync.
Learn more below about how it works and getting started:
- Syncing a specification
- How sync identifies unique operations
- Parameter and header default values
- Syncing OpenAPI or Swagger definitions
- Syncing Postman collections
Syncing a specification
Tests can be synced in two ways:
- Importing new tests from an OpenAPI, Swagger or Postman collection.
- Re-importing an existing OpenAPI, Swagger, or Postman import from a URL.
Syncing tests from a new import
When you import new tests on an existing web service, Assertible will look for any previous imports from the same specification. This is useful if you are importing your spec from a file or want to sync only certain tests:
Syncing tests from an existing import
When you import a specification from a URL, Assertible saves that information so you can easily sync with the specification hosted on that URL at the click of a button or using a simple API call.
A list of these available imports can be found on the Imports tab of your web service's Settings page:
How sync identifies unique operations
It's important to understand how Assertible uses the information in your import source to identify and import unique tests so that you can use the full power of sync to your advantage.
Assertible iterates through each unique definition (
Item for Postman Collections) in your spec and creates or
updates tests based on two distinct processes:
Identify a unique determinstic key for the test
For OpenAPI/Swagger definitions, each unique
Operation) is defined as a unique Assertible test. This behavior can be overriden using
operationId. See the section below on syncing OpenAPI/Swagger documents for more details.
For Postman Collection definitions, each unique collection
Itemis defined as a unique Assertible test. This behavior can be overriden using
idparameter. See the section below on syncing Postman collections for more details.
Map data and populate your Assertible test from your unique spec item
Assertible uses as much information as possible to intuitively use the information from your spec to configure as much test and assertion data as possible. Unintrusive defaults that are the most likely to result in a successful test run with the least necessary configuration are used when possible.
See the respective sections for OpenAPI, Swagger, and Postman below for a comprehensive guide on what fields in a spec map to Assertible test configuration values.
Parameter and header default values
Assertible uses some simple conventions to determine which parameter values are used for testing.
In particular, sync looks at the values in the
required fields, then creates tests using the rules described
below to determine which value to assign to each parameter.
example parameter overrides
By convention, sync prefers the value for the
example parameter to the value
default parameter. The
default value is used only when no
example value is specified.
Also by design, the sync process preserves the enabled/disabled status of parameters and headers across successive sync operations. So from the Test page, you can manually enable/disable any parameter(s), and be confident that all subsequent sync or import actions will preserve those settings automatically.
Assertible will import optional parameters (those tagged with
when there is a default value specified, but they'll be disabled for test
purposes. Those parameters will be shown as "undefined" on the Test page.
No validation of data types
It's also important to remember that sync does not validate the data type of any parameter. That means the sync process will create tests according to the preferences described above whether the selected values match the specified data type or not. While that helps avoid tedious interruptions to the sync process, it doesn't prevent test failures due to type mismatch errors. If a test fails, be sure to check for data type mismatches as part of initial troubleshooting.
Syncing OpenAPI or Swagger definitions
By default, when you import an OpenAPI or Swagger definition Assertible creates
a test for each unique
Operation. In practice,
this is determined using the
ENDPOINT/METHOD as the key for each test.
In practice, this means that if you change the operation's
PUT in your spec, Assertible will create a new test and sync that for all
operationIdfield on your item will override Assertible's default unique test identification, giving you complete control over all future updates to a specific test.
OpenAPI import fields
See the legend below for references to OpenAPI documentation
|Assertible field||OpenAPI field||Default|
|endpoint||The key of the
|method||The key of the
||Combination of operation and path name|
|query parameters||For each
|auth||Auth is imported to your web service's environment based on the
||Uses default auth if no other options are available|
|status code assertion||Imported from
|json schema assertion||Imported from
See our blog post Sync changes from OpenAPI/Swagger specifications with Assertible API tests for more details on how this feature works.
Syncing Postman Collections
By default, when you import a Postman Collection Assertible creates a test for
However, Assertible still ensures unique tests by using a combination of the
METHOD/ENDPOINT to reliably sync future changes.
idfield on your item to override Assertible's default unique test identification to have complete control over all future updates to a specific test.
Postman Collection import fields
See the Postman Collection Schema docs for clarification on references the references in the table below.
|Assertible field||Postman Collection field||Default|
|endpoint||The path portion of the request url.||
||Combination of operation and path name|
|query parameters||Extracted from the request url.||
|request body||The item
|status code assertion||Status code