GraphQL
- GraphQL
- Introduction
- What Can You Achieve with Specmatic’s GraphQL Support?
- Quick Start
- Detailed explanation
- Sample Projects
Introduction
Specmatic supports service virtualization, contract testing and backward compatibility for GraphQL APIs based on GraphQL SDL (Schema Definition Language) files, similar to its support for REST (OpenAPI).
What Can You Achieve with Specmatic’s GraphQL Support?
With Specmatic GraphQL support you will be to leverage your GraphQL SDL files as executable contracts.
- Intelligent Service Virtualisation: Stub out GraphQL services for testing and development
- Contract Testing: Validate requests and responses against your GraphQL SDL files
- Backward Compatibility Checks: Compare two versions of your GraphQL SDL files to identify breaking changes without writing any code
- Central Contract Repo: Store your GraphQL SDL files in central Git repo which will serve as single source of truth for both providers and consumers
- API resiliency : Generate negative and edge cases to verify the resiliency of your API impementation based on your GraphQL SDL files.
Quick Start
Here is a sample project which has a detailed animated architecture diagram along with explanations about how we are isolating the System Under Test when running Contract Tests.
Clone the project and follow the instructions in the README.
Detailed explanation
Using your GraphQL files as your API Contracts from Central Contract Repository
- Store your GraphQL SDL files in a central repository for easy access and version control.
- Create a
specmatic.yaml
file in the root of your project to reference these contracts. Here’s an example:
contract_repositories:
- type: git
repository: https://github.com/znsio/specmatic-order-contracts.git
provides:
- io/specmatic/examples/store/graphql/products_bff.graphqls
consumes:
- io/specmatic/examples/store/openapi/api_order_v3.yaml
Make sure to update the repository
, provides
and consumes
sections to reflect your actual contract repository and .graphqls file locations.
Using externalised examples as test / stub data to be used as part of contract tests and service virtualization respectively
Suppose you have a GraphQL SDL file as shown below.
enum ProductType {
gadget
book
food
other
}
type Query {
findAvailableProducts(type: ProductType!, pageSize: Int): [Product]
}
type Product {
id: ID!
name: String!
inventory: Int!
type: ProductType!
}
In order to provide appropriate example values, you can create an example YAML file that has test/stub data pertaining to the findAvailableProducts
query.
request:
httpHeaders:
X-region: north-west
body: |
query {
findAvailableProducts(type: gadget, pageSize: 10) { id name inventory type }
}
response: [
{
"id": "10",
"name": "The Almanac",
"inventory": 10,
"type": "book"
},
{
"id": "20",
"name": "iPhone",
"inventory": 15,
"type": "gadget"
}
]
This file can either be stored in a directory that is colocated with the GraphQL SDL file with the naming convention <GraphQL SDL file without extension>_examples
, or alternatively you can pass it as an argument programmatically or through CLI args while running tests or service virtualisation.
Let us now take deeper look at the external example format.
- At the top level we have two YAML root nodes called
request
andresponse
request
can hold the following keys:body
: this can contain eitherquery
s ormututation
s with exact values where necessaryheaders
: you can add yourHTTP
headers here
response
holds responses with JSON syntax for readability, syntax highlighting and also as an aid to copy and paste of real responses from actual application logs etc.
HTTP Headers
Although GraphQL SDL files do not support HTTP request headers, you may directly add them to your Specmatic example files in httpHeaders
under the request
key, as seen in the example yaml in the previous section. The headers will be leveraged if present both by the contract tests as well as service virtualization.
GraphQL Variables
Specmatic supports usage of GraphQL variables seamlessly. You only need to make sure that the externalised example is structured such that it uses the actual field values inline instead of variables in the query. Here is an example.
Say suppose, below request is that is being sent by your GraphQL Consumer to Specmatic GraphQL service virtualization server.
{
"operationName": "FindAvailableProducts",
"variables": {
"type": "gadget",
"pageSize": 10
},
"query": "query FindAvailableProducts($type: ProductType!, $pageSize: Int!) { findAvailableProducts(type: $type, pageSize: $pageSize) { id name inventory type } }"
}
As you can see, the above request from GraphQL consumer includes a variable called $pageSize
. However in our example we will not be using it, instead we will be using the actual value (pageSize: 10
) to match a request that comes with that value.
request:
body: |
findAvailableProducts(type: "gadget", pageSize: 10) {
id
name
inventory
type
}
response: [
{
"id": "10",
"name": "The Almanac",
"inventory": 10,
"type": "book"
},
{
"id": "20",
"name": "iPhone",
"inventory": 15,
"type": "gadget"
}
]
Note: It is recommended to specify the type of the variable e.g. $pageSize: Int!
. If the type is not specified explicitly you may face some issues since Specmatic will implicitly cast the variable to a certain type which may be invalid sometimes.
GraphQL Scalar Types
In GraphQL, you can define custom scalar types to handle specialized data, such as dates or monetary values, that require specific serialization and deserialization logic. For example:
schema {
query: Query
mutation: Mutation
}
scalar Date
type Offer {
offerCode: String!
validUntil: Date!
}
type Query {
findOffersForDate(date: Date!): [Offer]!
}
In this schema, Date
is a custom scalar. While GraphQL doesn’t provide details on how this scalar is serialized or deserialized, your application code defines the logic.
When testing queries like findOffersForDate
using Specmatic, the tool doesn’t know how to correctly handle the Date
scalar and might pass an incorrect value, such as a random string, leading to test failures.
To guide Specmatic, you can provide externalized examples that specify valid inputs for custom scalars like Date
. For instance:
request:
body: |
query {
findOffersForDate(date: "2024/12/31") { offerCode, validUntil }
}
response: [
{
"offerCode": "WKND30",
"validUntil": "2024/12/12"
},
{
"offerCode": "SUNDAY20",
"validUntil": "2024/12/25"
}
]
Here, the Date
scalar is provided with a valid value ("2024/12/31"
). This ensures that during testing, Specmatic uses the correct format for the Date
argument, allowing your tests to run smoothly without failures caused by incorrect data types.
Using the Docker Image
So far in the above explanation the sample project is invoking Specmatic GraphQL support programmatically. However if you wish to run the same using the CLI then the Docker image below wraps the same Specmatic GraphQL capabilities.
Also the Specmatic GraphQL Docker image, by nature, is completely language and tech stack agnostic.
Starting the Stub / Service Virtualization Service
To start the stub service, use the following command:
docker run --network host -p 8090:8090 -v "$(pwd)/specmatic.yml:/usr/src/app/specmatic.yml" znsio/specmatic virtualize --port=8090
This command mounts your local specmatic.yaml
file into the container, exposes the stub service on port 8090, and uses the GraphQL SDL files listed under consumes
section for starting up a service virtualisation server.
Running Tests
To run contract test:
docker run --network host -v "$(pwd)/specmatic.yml:/usr/src/app/specmatic.yml" -v "$(pwd)/build/reports/specmatic:/usr/src/app/build/reports/specmatic" -e SPECMATIC_GENERATIVE_TESTS=true znsio/specmatic-graphql-trial test --port=8080
This command mounts your specmatic.yaml
file and runs tests against a service running on port 8080 by generating GraphQL requests based on the GrapqhQL SDL files listed under provides
section along with examples if any provided in the colocated directory named <GraphQL SDL file without extension>_examples
. Also, it mounts the build artifacts from the docker container onto your local machine once the test run is completed.
Sample Projects
We have created sample projects to demonstrate the above in different languages and scenarios. Please follow the link for the latest sample projects .
These projects provide practical examples of how to integrate Specmatic GraphQL support into your workflow, including setting up stubs, writing tests, handling different languages, frameworks and running them on CI like Github actions.