10 Setting Up a GraphQL Playground for Query Testing
10 Setting Up a GraphQL Playground for Query Testing
GraphQL is rapidly becoming the de facto standard for managing API data thanks to its strengths in query flexibility and data efficiency. However, testing queries can sometimes be a challenge of its own, especially if you are new to the world of GraphQL or do not yet know the right tools. A GraphQL Playground is the favorite solution for many engineers when exploring and testing queries before moving into production code implementation. In this article, we will walk through 10 practical steps for setting up a GraphQL Playground so that query testing becomes seamless and efficient.
1. What Is a GraphQL Playground?
A GraphQL Playground is an interactive web-based interface that lets developers run queries, mutations, and even subscriptions against a GraphQL API. Think of it as the “Postman” of the GraphQL ecosystem, but more interactive and far more enjoyable to use for experimenting with queries.
Some of its key features:
- Automatic schema documentation
- Syntax autocompletion
- Custom header support (for example, Authorization)
- Query history and variable simulation
- Multiple endpoint environments
Popular Playground tools include: GraphQL Playground (the original), Altair, Apollo Sandbox, and Insomnia.
2. Installing the Playground
For local development, there are two main options:
- Use a third-party web app such as https://www.graphqlbin.com/ or https://www.apollographql.com/sandbox/
- Attach Playground middleware to your local server
Example of adding a Playground to Express.js:
1const express = require('express');
2const { graphqlHTTP } = require('express-graphql');
3const { buildSchema } = require('graphql');
4const { expressPlayground } = require('graphql-playground-middleware');
5
6const schema = buildSchema(`
7 type Query {
8 hello: String
9 }
10`);
11
12const root = {
13 hello: () => 'Hello world!'
14};
15
16const app = express();
17
18app.use('/graphql', graphqlHTTP({
19 schema: schema,
20 rootValue: root,
21 graphiql: false
22}));
23
24app.get('/playground', expressPlayground({ endpoint: '/graphql' }));
25
26app.listen(4000, () => console.log('Server berjalan di http://localhost:4000/playground'));3. Connecting to the Playground
After installation, open your browser to the Playground endpoint, for example http://localhost:4000/playground. You will see an interactive UI like the following:
On the left side, you can write your query. The response will appear on the right.
4. Exploring the Automatic Documentation
One of the Playground’s main value-adds is live, schema-based documentation. Simply click the “Docs” icon and a schema tree will appear, complete with data types, fields, and descriptions.
Documentation Example:
| Type | Field | Description |
|---|---|---|
| Query | hello: String | Greeting text |
| Mutation | createUser | Create a new user |
This feature is incredibly helpful when exploring a new API without having to read manual documentation.
5. Trying Out a Basic Query
Let’s start by writing a simple query:
1query {
2 hello
3}Expected Response:
1{
2 "data": {
3 "hello": "Hello world!"
4 }
5}Notice the field autocompletion and type checking in real time. This will save you a lot of debugging time on typos.
6. Adding Variables to a Query
The Playground allows the use of variables to simulate dynamic scenarios.
1query SayHello($name: String!) {
2 hello(name: $name)
3}1{
2 "name": "Budi"
3}7. Simulating Authorization
GraphQL APIs often require an Authorization header. The Playground makes it easy to add headers via the HTTP HEADERS icon in the top right.
1{
2 "Authorization": "Bearer YOUR_SECRET_TOKEN"
3}Take a look at the following flow diagram for a request with a header:
sequenceDiagram
participant U as User
participant P as Playground
participant S as GraphQL Server
U->>P: Menulis query & masukkan token di HTTP HEADERS
P->>S: Mengirim query main endpoint + Authorization header
S->>P: Validasi token, proses query, kirim response
P->>U: Tampilkan response di UI
8. Testing Mutations and Error Handling
Mutations are no less important than queries.
1mutation {
2 createUser(username: "budi", password: "pass123") {
3 id
4 username
5 }
6}Error scenarios can be simulated with invalid input:
1mutation {
2 createUser(username: "", password: "")
3}9. Multi-Environment & Mock Data
You can switch the Playground endpoint to a different environment, such as staging or production, or use a mocking tool like https://mocki.io/ for a fake schema.
| Env | Endpoint |
|---|---|
| Staging | https://staging-api.com/graphql |
| Production | https://api.com/graphql |
| Mock | https://mocki.io/v1/1234 |
Just click in the settings, no need to restart the server.
10. Real Case: Testing an Application
To wrap up, here is the workflow for testing queries before the frontend consumes them:
flowchart TD
A[Frontend Dev buka Playground]
B[Menulis query kebutuhan fitur baru]
C[Mengecek response dan simulasi variable]
D[Testing dengan header Auth]
E[Query siap dikonsumsi Frontend]
A --> B --> C --> D --> E
This step ensures the integration runs smoothly without any API mismatches, boosting the productivity of both the frontend and backend teams.
Conclusion
Making use of a GraphQL Playground is a mandatory workflow for every modern engineer during query development and testing. From schema exploration and authorization simulation to error testing, everything can be done within a single UI. Many engineering teams even make Playground queries part of automating their documentation and regression testing before releasing an API to a production application.
Treat this Playground as a mini “laboratory” before your GraphQL queries are actually consumed by an application, because the best debugging is the kind done at the playground level, not in production!