Glean Local Dev Loop

Overview

Local development workflow for Glean enterprise search API integration. Provides a fast feedback loop with mock search results, connector testing, and document indexing simulation so you can build custom datasource connectors and search UIs without needing a live Glean deployment. Toggle between mock mode for rapid connector iteration and sandbox mode for validating against your Glean instance.

Environment Setup

cp .env.example .env
# Set your credentials:
# GLEAN_API_KEY=glean_xxxxxxxxxxxx
# GLEAN_INSTANCE=https://your-company.glean.com
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) {
  app.use("/api", createProxyMiddleware({
    target: process.env.GLEAN_INSTANCE,
    changeOrigin: true,
    headers: { Authorization: `Bearer ${process.env.GLEAN_API_KEY}` },
  }));
} else {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
}
app.listen(3003, () => console.log(`Glean dev server on :3003 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic enterprise search responses
export function mountMockRoutes(app: any) {
  app.post("/api/search", (req: any, res: any) => res.json({
    results: [
      { title: "Q4 Engineering Roadmap", url: "https://wiki.co/roadmap", score: 0.97, datasource: "confluence",
        snippets: [{ snippet: "The <b>roadmap</b> includes migration to..." }] },
      { title: "Onboarding Guide", url: "https://wiki.co/onboard", score: 0.88, datasource: "notion",
        snippets: [{ snippet: "New hire <b>onboarding</b> steps..." }] },
    ],
    totalCount: 2,
  }));
  app.post("/api/index/documents", (req: any, res: any) => res.json({
    status: "OK", documentsIndexed: req.body.documents?.length || 0,
  }));
  app.get("/api/datasources", (_req: any, res: any) => res.json([
    { name: "confluence", displayName: "Confluence", docCount: 1250 },
    { name: "notion", displayName: "Notion", docCount: 430 },
  ]));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
MOCK_MODE=false npm run test:integration  # Integration test against real Glean instance

Debug Tips

• Use curl -X POST http://localhost:3003/api/search -d '{"query":"test"}' to verify mock search
• Glean connectors must return documents with id, title, body.textContent, and datasource fields
• Check connector transform output shape before pushing to the indexing API
• Enable verbose logging on the Glean SDK client to trace API call timing
• Verify OAuth scopes if search returns empty results against a live instance

Error Handling

Prerequisites

• A local mock or sandbox endpoint, a fictitious datasource, and no production token in environment files, shell history, or test output.
• A fixture reset command and two synthetic identities for access-boundary tests.
• A change record and rollback path for any configuration that might later be promoted.

Instructions

1. Start in mock mode with bounded fixtures and validate transforms, rejection paths, and redaction before any network call.
2. Use a sandbox datasource with a scoped credential only after local tests pass; assign an idempotency key and verify both allow and deny cases.
3. Keep logs to opaque IDs, status, counts, and correlation values; inspect payloads only in the local fixture directory.
4. Reset fixtures and revoke temporary credentials after the run, then attach a redacted receipt to the change.

Output

Return a local-loop receipt with fixture revision, environment, datasource, tests run, allow/deny outcomes, temporary credential reference, and cleanup state. Exclude tokens, real documents, and search text.

Examples

fixtures=v7; mode=mock->sandbox; source=dev-synthetic; tests=12/12; allow=pass; deny=pass; cleanup=complete is a safe promotion candidate.

Resources

• Glean Indexing API
• Glean Search API

Next Steps

See glean-debug-bundle.