DEV Community

Cover image for Test Notion database queries without a workspace
FetchSandbox
FetchSandbox

Posted on

Test Notion database queries without a workspace

#notion #api #testing #webdev

Testing a Notion database query sounds simple until you try to do it in a real workspace.

You need a workspace. You need an integration token. You need to share the right database with that integration. You need seed pages with the right properties. Then you run the query and hope you did not pollute somebody's actual team dashboard with test rows.

The painful part is not POST /v1/databases/{database_id}/query.

The painful part is proving the whole shape around it:

  • does the database exist?
  • do the properties match what your app expects?
  • does the filter return the right rows?
  • does the response shape match the code path you are about to ship?
  • can you repeat the test without cleaning up a real Notion workspace?

The specific workflow

The narrow workflow I care about here is:

  1. Retrieve a Notion database
  2. Query that database for high-priority in-progress tasks
  3. Verify the returned page shape before wiring it into an app

In FetchSandbox, the workflow is intentionally small:

GET  /v1/databases/db-a1b2c3d4-e5f6-7890-abcd-ef1234567890
POST /v1/databases/db-a1b2c3d4-e5f6-7890-abcd-ef1234567890/query
Enter fullscreen mode Exit fullscreen mode

The query body filters by two properties:

{
  "filter": {
    "and": [
      {
        "property": "Status",
        "select": {
          "equals": "In Progress"
        }
      },
      {
        "property": "Priority",
        "select": {
          "equals": "High"
        }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

That is the kind of test I want before touching production code.

Not "does the endpoint return 200?"

More like:

database exists -> properties match -> filter runs -> rows come back -> app can trust the shape
Enter fullscreen mode Exit fullscreen mode

Why docs and mocks miss this

Docs usually show the endpoint and a sample payload.

That helps, but it does not answer the messy integration questions:

  • what happens when the database is missing?
  • what if the integration does not have access?
  • what if the property name is different from the sample?
  • what if the query returns zero pages?
  • what fields should my app treat as stable?

Generic mocks usually miss this too because they return static JSON. They do not behave like a workspace with pages, databases, users, blocks, comments, and state.

For a Notion integration, state matters.

If your app reads tasks from Notion, the test needs to prove more than the request syntax. It needs to prove that your app can survive the workspace shape it expects.

How I would test it

For this workflow, I would test three cases:

1. Happy path

The database exists and contains matching pages.

Expected result:

GET database -> 200
POST query -> 200
matching pages returned
Enter fullscreen mode Exit fullscreen mode

This proves the app can read the expected database shape.

2. Permission denied

The database exists, but the integration should not be allowed to read it.

Expected result:

POST query -> 403
app shows setup guidance instead of crashing
Enter fullscreen mode Exit fullscreen mode

This is the case most teams discover only after connecting a real workspace with incomplete permissions.

3. Empty result

The query is valid, but no pages match Status = In Progress and Priority = High.

Expected result:

POST query -> 200
results: []
app shows an empty state
Enter fullscreen mode Exit fullscreen mode

This catches a surprising number of UI and sync bugs.

Where FetchSandbox fits

This is the kind of workflow a stateful API sandbox should prove.

With the Notion sandbox in FetchSandbox, you can test pages, databases, blocks, users, comments, and search without setting up a real workspace or using a real integration token.

I recorded a raw walkthrough of this Notion database workflow here:

https://youtube.com/watch?v=xJpJ5dOR_Co

The more interesting path is connecting your IDE to it.

FetchSandbox MCP lets Cursor, Claude, or another MCP-capable agent discover and run these workflows from your own development environment:

{
  "mcpServers": {
    "fetchsandbox": {
      "command": "npx",
      "args": ["-y", "fetchsandbox-mcp"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Then you can ask the agent something like:

Use FetchSandbox MCP to explore the Notion sandbox.
Run the database query workflow and explain what response shape my app should handle.
Enter fullscreen mode Exit fullscreen mode

That changes the workflow from "read docs and copy examples" to "run the integration behavior from inside the IDE."

The Notion portal is here:

https://fetchsandbox.com/docs/notion

And the Notion landing page is here:

https://fetchsandbox.com/notion

The goal is not to replace Notion.

The goal is to give developers a runnable place to understand the API lifecycle before they wire it into a real customer workspace.

For this one workflow, the question is simple:

Can my app query a Notion database and handle the response shape correctly?

That should be testable before production.

Top comments (0)