Introducing GraphErrQL
An end-to-end query testing platform for GraphQL
When I am not coding, I am usually baking. To make a perfect French fruit tart, the vanilla custard must be smooth and rich, the fruit on top must be cut “just-right”, and the glaze must add some flavor, sweetness and shine. These elements must be nestled in a pastry shell that is buttery, crisp and not too thick. These individual elements must be perfect, but the tart as a whole must also work together through a union of flavors, textures, and acidity to be a success. You need to see how the elements work together in different bites to assess your recipe.
Coding is remarkably similar. Our functions, components, and even “ends” of the application can be written in beautiful code, but the application is a flop if the parts are not integrated.
Introducing GraphErrQL
Current GraphQL dev tools allow engineers to write single queries in a sandbox environment, but do not assist in the next step towards integration: showing the responses to queries sent from the front end. Troubleshooting errors can require diving deep into dev tools and using numerous console logs. For this reason, the GraphErrQL team built a new GUI that integrates into Express-based host applications for drafting GraphQL Queries in a sandbox mode as well as viewing incoming Queries from the Host App via a live-listening mode. GraphErrQL also provides a platform for displaying contextualized error feedback for all stages of GraphQL development. By getting the full response in a separate window, developers can split the screen and write or test front-end queries side-by-side, minimizing the need for repeated console logging and scrolling through their terminals. All in a fun user interface!
A Refresher on GraphQL
For those that need a refresher, GraphQL is a query language that enables users to request only the specific data they want- eliminating over-fetching or the need to send repeated requests to the API. By only needing to send one query to get all of the information needed and reducing the size of the response, users get data back faster even on slow or mobile connections. With GraphQL, arguments can be passed in for each field in a query, and fragments can help maintain DRY and organized code. It is not a surprise that GraphQL went from under 400,000 weekly downloads at the beginning of 2018 to over 8.5 million weekly downloads in June 2022 according to npm trends.
But GraphQL has a steep learning curve– our goal with GraphErrQL is to attenuate it! Tools that make it easier for teams to adopt GraphQL will ultimately improve user experience across the internet as the implementation no longer feels like an insurmountable barrier.
How GraphErrQL works
GraphQL developers may be familiar with a popular built-in IDE, GraphiQL, where users can draft queries against their application Back End in a sandbox mode, prior to implementing those Queries in Front End files. GraphErrQL combines a similar sandbox mode with a live-listening mode to test queries sent from the Front End of their application and allows users to seamlessly toggle between modes. This empowers GraphQL development and iteration through the full application lifecycle, rather than only in early phases.
In sandbox mode, GraphErrQL uses CodeMirror and communicates bidirectionally with the /graphql endpoint of the host application to run queries and view responses.
The live-listening mode involves an SSE (Server-Sent-Event) connection that connects the host application’s /graphql endpoint with the GraphErrQL middleware application. This connection is instantiated upon initial rendering of GraphErrQL. Queries are sent from the host app Front End to the /graphql endpoint, and are stored in a middleware cache. Once the SSE connection is set up and the cached queries are sent, additional Queries are forwarded live across the SSE connection to the /grapherrql endpoint. Queries are then processed by GraphQLHTTP, and responses are stored and forwarded in the same way. Thus, the GraphErrQL GUI receives both the initial query and the processed response.
How to set up GraphErrQL
GraphErrQL is available to download as a npm package. To start using this dev tool, run the following commands in your terminal:
npm i grapherrqlnpm i grapherrql-express
In the server file, add each of the following to build the SSE connection:
Require Needed Exports:
const { graphqlHTTP } = require(‘express-graphql’);const { directoryPath, defaultFilePath } = require (‘grapherrql’);const { grapherrql, eventsHandler, serveGrapherrql,} = require(‘grapherrql-express’);
Call Express, define the server port and setup the encoding:
const PORT = ‘3001’;const app = express();app.use(express.json());app.use(express.urlencoded({extended: false}));
Set up the base GraphQL endpoint:
app.use(‘/graphql’, grapherrql(graphqlHTTP, schema));Set up events endpoint for the SSE:
app.get(‘/events’, eventsHandler);Point the static file requests to GraphErrQL node_module:
app.use(express.static(directoryPath))Finally, set up the GraphErrQL endpoint:
app.get(‘/grapherrql’, serveGrapherrql(PORT, defaultFilePath));Once the code has been copied into the host application, GraphErrQL is ready to run! To start GraphErrQL, start the host-app server, and then two browser terminals. The first browser terminal should open the host-app front end. The second browser terminal should access <host_app><server_port>/grapherrql, which launches GraphErrQL. GraphErrQL is now ready to test queries and mutations in both live and sandbox modes!
Conclusion
The GraphErrQL team has been working hard to make writing queries easier for the GraphQL development community. We would like to continue to grow GraphErrQL, specifically in addressing improved error handling features. We feel that this new platform offers an excellent opportunity to do so. Interested developers can check out the repo on GitHub, and we welcome any feedback and improvements. We are always happy to review pull requests from the community. And if you used GraphErrQL and appreciated its functionality, we ask that you give us a star on GitHub!
The Team
The GraphErrQL team consists of Josh Merrell, Jerald Stephenson, Mariah Talicuran, and Gwen Phillips who have all helped make GraphErrQL, and this article, available. GraphErrQL is an Open Source Project accelerated by OS Labs.