Automating GraphQL Schema Validation with @graphql-tools and @graphql-inspector
In modern web development, GraphQL has become a powerful tool for API design, providing flexibility and efficiency. However, as your API evolves, it's crucial to ensure that the queries used in your frontend application remain up-to-date and not deprecated.
In the example above, we observe that the GraphQL schema includes a deprecated query and field. Consequently, our frontend application may be compromised, and our apps could become outdated.
This blog post will guide you through automating the validation of your GraphQL queries using @graphql-tools and GraphQL Inspector. By implementing this validation, you can maintain the integrity of your application and ensure that your queries are always compatible with the latest schema changes.
You can check the official repo with the full code
Considerations
Before diving into the implementation, consider the following steps to set up your project:
Project Setup:
Whether you're using React, Flutter, or another framework for your frontend application, you'll create a separate folder for the validation script.
Create a new directory named
scriptwithin your project.
Initialize a Node.js Project:
Navigate to the script directory and initialize a new Node.js project:
cd script;
npm init -y;Create a
validaton-script.jsfile
Install Dependencies:
Install the necessary dependencies:
npm install @graphql-inspector/core @graphql-tools/load @graphql-tools/url-loader fs graphql-tag pathSchema and Queries:
Ensure your GraphQL schema is accessible from an endpoint, and you have your GraphQL queries defined in a file.
React file example:
const GET_USER = gql`
query getUser($id: Int!) {
getUser(id: $id) {
id
name
}
}
`;Flutter file example:
class GraphQLAPIDefinitions {
static const getUser = r'''
query getUser($id: Int!){
getUser(id: $id) {
id
name
}
}
''';
}With these steps completed, you'll have your environment set up and ready to create and run the validation script.
Validation Script
Now, let's dive into the process of writing the script to automate the validation of our GraphQL queries.
Gathering Tools:
First, we need to gather the essential Node.js modules and libraries required for our script. We use
@graphql-tools/loadand@graphql-tools/url-loaderto fetch the GraphQL schema,graphql-inspectorto validate it,fs.promisesandpathto work with the file system, andgraphql-tagto parse the GraphQL queries.
const { loadSchema } = require("@graphql-tools/load");
const { UrlLoader } = require("@graphql-tools/url-loader");
const { validate } = require("@graphql-inspector/core");
const fs = require("fs").promises;
const path = require("path");
const gql = require("graphql-tag");Setting Up the Scene:
Next, we define the constants needed for our task.
GRAPHQL_ENDPOINTspecifies the URL where our GraphQL schema resides.DEFINITIONS_FILE_PATHspecifies the path to our GraphQL query definitions file.
const GRAPHQL_ENDPOINT = "https://your-url/graphql";
const DEFINITIONS_FILE_PATH = path.join(
__dirname,
"your-graphql-file-definitions-path"
);Fetching the Schema:
The function
loadSchemaFromEndpointis responsible for fetching the schema from the specified endpoint usingUrlLoader.
async function loadSchemaFromEndpoint(endpoint) {
return loadSchema(endpoint, {
loaders: [new UrlLoader()],
});
}Reading the Definitions:
The function
readDefinitionsFromFilereads the query definitions from a file. This is crucial as it contains the GraphQL queries used in the frontend application.
async function readDefinitionsFromFile(filePath) {
return fs.readFile(filePath, "utf-8");
}Extracting Queries:
extractQueriesFromDefinitionsuses a regular expression to extract queries from the definitions file. Each query is parsed and prepared for validation.
function extractQueriesFromDefinitions(data) {
const regex = /(query|mutation)\s+[a-zA-Z0-9_]+\s*\([^)]*\)\s*\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/gm;
const sources = [];
for (const match of data.matchAll(regex)) {
const query = match[0];
const parsedQuery = gql`${query}`;
const queryName = parsedQuery.definitions[0].name?.value;
sources.push({ ...parsedQuery.loc.source, name: queryName });
}
return sources;
}if you need to handle more complex queries, please adjust the regex to match with you need.
Validating and Logging:
logAndExitprocesses the validation response. It filters out deprecated fields, logs them, and exits the process with a success or error code based on the findings.
function logAndExit(response) {
const deprecatedFields = response
.filter((item) => item.deprecated.length > 0)
.map((item) => {
item.deprecated.forEach((itemDeprecated) => {
console.log(
`Deprecated fields on: ${item.source.name || ""}`,
itemDeprecated.message
);
});
return item.deprecated;
})
.flat();
process.exit(deprecatedFields.length > 0 ? 1 : 0);
}Executing the Script:
In the
mainfunction, we coordinate the entire process. We start by loading the schema from the endpoint, then read the query definitions from the file, extract the queries, and validate them against the schema. The results are logged and the process exits based on the validation outcome.
async function main() {
try {
const schema = await loadSchemaFromEndpoint(GRAPHQL_ENDPOINT);
const definitionsData = await readDefinitionsFromFile(DEFINITIONS_FILE_PATH);
const sources = extractQueriesFromDefinitions(definitionsData);
const response = validate(schema, sources, {
strictDeprecated: true,
});
logAndExit(response);
} catch (error) {
console.error("An error occurred:", error);
process.exit(1);
}
}Finally, we call the main function to initiate the validation process.
main();We can test it using the follow command:
node graphql-validator/graphql-validator-script.js
Full code:
const { loadSchema } = require("@graphql-tools/load");
const { UrlLoader } = require("@graphql-tools/url-loader");
const { validate } = require("@graphql-inspector/core");
const fs = require("fs").promises;
const path = require("path");
const gql = require("graphql-tag");
const GRAPHQL_ENDPOINT = "http://localhost:3000/graphql";
const DEFINITIONS_FILE_PATH = path.join(
__dirname,
"./graphql-definitions.txt"
);
async function loadSchemaFromEndpoint(endpoint) {
return loadSchema(endpoint, {
loaders: [new UrlLoader()],
});
}
async function readDefinitionsFromFile(filePath) {
return fs.readFile(filePath, "utf-8");
}
function extractQueriesFromDefinitions(data) {
const regex = /(query|mutation)\s+[a-zA-Z0-9_]+\s*\([^)]*\)\s*\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/gm;
const sources = [];
for (const match of data.matchAll(regex)) {
const query = match[0];
const parsedQuery = gql`${query}`;
const queryName = parsedQuery.definitions[0].name?.value;
sources.push({ ...parsedQuery.loc.source, name: queryName });
}
return sources;
}
function logAndExit(response) {
const deprecatedFields = response
.filter((item) => item.deprecated.length > 0)
.map((item) => {
item.deprecated.forEach((itemDeprecated) => {
console.log(
`Deprecated fields on: ${item.source.name || ""}`,
itemDeprecated.message
);
});
return item.deprecated;
})
.flat();
process.exit(deprecatedFields.length > 0 ? 1 : 0);
}
async function main() {
try {
const schema = await loadSchemaFromEndpoint(GRAPHQL_ENDPOINT);
const definitionsData = await readDefinitionsFromFile(DEFINITIONS_FILE_PATH);
const sources = extractQueriesFromDefinitions(definitionsData);
const response = validate(schema, sources, {
strictDeprecated: true,
});
logAndExit(response);
} catch (error) {
console.error("An error occurred:", error);
process.exit(1);
}
}
main();Using the Pipeline to Automate
Integrate the validation script into your CI/CD pipeline to automate schema validation. Here's an example using GitHub Actions:
Create a Workflow File:
Add a
.github/workflows/schema-validation.ymlfile to your repository.
Define the Workflow:
name: GraphQL Schema Validation
on: [pull_request]
jobs:
validate-schema:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- run: cd graphql-validator && npm install
- run: node graphql-validator/graphql-validator-script.jsWith this setup, every push and pull request will trigger the schema validation, ensuring that any changes to your schema are promptly validated and errors are caught early in the development process.
Conclusion
Automating the validation of your GraphQL queries is a critical step in maintaining the integrity of your frontend applications. By leveraging @graphql-tools and GraphQL Inspector, you can ensure that your queries remain compatible with the evolving schema. This automation not only saves time but also enhances the reliability of your application. Integrating this validation into your CI/CD pipeline ensures that any issues are detected early, keeping your development process smooth and efficient.
