How to Write Integration Tests with Groq (Step by Step)

How to Write Integration Tests with Groq

We’re building real-world integration tests with Groq to ensure our data-driven applications work as intended. Testing in the real world is critical because a single error in data retrieval can cascade into major issues—I’ve been there, trust me.

Prerequisites

• Node.js 14.x or higher
• npm 6.x or higher
• Sanity CLI installed globally: npm install -g @sanity/cli
• Groq version 1.0.0 or higher

Step 1: Set Up Your Sanity Project

First things first, you need a Sanity project. This is the environment where Groq lives and breathes. If you’re testing data queries, you need to have a schema set up already.

sanity init --dataset production

By running the above command, you’re creating a new Sanity project with a default dataset. Make sure to fill out the prompts with your happy thoughts.

Step 2: Define Your Groq Queries

Next, let’s define a simple Groq query based on your schema. For the sake of illustration, let’s assume you have a blog schema with documents for ‘posts’. Here’s how you would write a basic query:

const query = '*[_type == "post"]';

This is the simplest form of querying all posts. As you build more complex queries, remember: clarity is vital. A confusing query might seem like no big deal during development, but when things break in production, it’s a nightmare.

Step 3: Set Up Your Integration Tests

In the world of integration tests, organizations often struggle with frameworks. Forget the usual suspects like Mocha or Jest. We’re going straight for the Sanity’s native test tools, which are designed to pair well with Groq.

Create Your Test Environment

This is where we set up the testing framework. You need to create a test file for your queries. Let’s say we name it integration.test.js.

const sanityClient = require('@sanity/client');
const client = sanityClient({
 projectId: 'yourProjectId',
 dataset: 'production',
 apiVersion: '2021-10-21',
 token: 'yourAuthToken',
 useCdn: false
});

Why the token? Because that’s how Sanity keeps the riff-raff out. Make sure you have an authenticated token with read access to your documents.

Write Your First Test

Now, let’s write a simple test to see if our query returns the expected results. Your query will return data that you need to validate.

const { expect } = require('chai');

describe('Groq Integration Tests', () => {
 it('should return all posts', async () => {
 const result = await client.fetch(query);
 expect(result).to.be.an('array');
 expect(result.length).to.be.greaterThan(0);
 });
});

The idea here is straightforward: you test if your query yields an array of posts. If it doesn’t, there’s a problem, right? Tricky part here can be the asynchronous nature of fetching data, which sometimes throws off first-time testers.

Run Your Tests

Time to execute those tests! To run your test file, invoke your test runner; if you’re using npm, it might look something like this:

npm test

Be prepared for some issues—nothing is ever simple. You may run into errors like fetching a nonexistent project ID. When that happens, double-check your environment variables; they need to be spot on.

The Gotchas

Let’s talk about those annoying little things they don’t cover in every tutorial:

• Versioning: Always use the latest version of Groq that aligns with your Sanity client. Features might not be backward-compatible.
• Data Structure Changes: If someone changes the schema and you don’t catch it in a test, prepare for some confusing errors.
• Async Errors: Make sure to handle promises and async/await correctly. Errors often bubble up because of mismanagement in pagination or fetching operations.
• Test Isolation: Don’t forget that tests can affect each other. Ensure that every test can run independently to avoid side effects.

Full Code

Let’s put all this together in one snippet so you can see the whole picture:

// integration.test.js
const sanityClient = require('@sanity/client');
const { expect } = require('chai');

const client = sanityClient({
 projectId: 'yourProjectId',
 dataset: 'production',
 apiVersion: '2021-10-21',
 token: 'yourAuthToken',
 useCdn: false
});

const query = '*[_type == "post"]'; // This is our Groq query

describe('Groq Integration Tests', () => {
 it('should return all posts', async () => {
 const result = await client.fetch(query);
 expect(result).to.be.an('array');
 expect(result.length).to.be.greaterThan(0);
 });
});

What’s Next

Once you’ve got integration tests written and running, it’s time to incorporate Continuous Integration (CI) tools like CircleCI or GitHub Actions. Set up your pipeline to automatically run these tests every time you push to your repository. It keeps your workflow streamlined and your code in top shape.

FAQs

• What if my tests are failing even though the query works? Check if the data in your Sanity project has changed since you last ran the test. Always ensure that your expectations match the current state of your dataset.
• How do I handle sensitive data in tests? It’s best to use environment variables for tokens and other sensitive data. Never hardcode this stuff into your test files!
• Can I run tests locally? Absolutely! Make sure all your local environment variables are set correctly, and you can run the tests just like you would in a CI/CD environment.

Data Sources

Check out the official Sanity documentation and the Groq guide for more details on queries and structuring your data.

Last updated April 01, 2026. Data sourced from official docs and community benchmarks.

🕒 Published: April 1, 2026