Skip to content

Disentinel/grafema / .claude/skills/grafema-test-backend-usage

grafema-test-backend-usage

Verified

Fix node query issues in Grafema tests when nodes have numeric IDs instead of human-readable IDs, or when `type` field is undefined. Use when: (1) queryNodes returns nodes with numeric IDs like "52710336597754872375318185843222727675" instead of semantic IDs like "net:request#__network__", (2) node.type is undefined but node.nodeType has a value, (3) metadata is a JSON string instead of parsed object, (4) tests fail with "Cannot read property 'length' of undefined" after queryNodes. Covers RFDBServerBackend vs RFDBClient distinction and async generator handling.

FileKindSize
SKILL.mdskill md4.6 KB
---
name: grafema-test-backend-usage
description: |
  Fix node query issues in Grafema tests when nodes have numeric IDs instead of
  human-readable IDs, or when `type` field is undefined. Use when: (1) queryNodes
  returns nodes with numeric IDs like "52710336597754872375318185843222727675"
  instead of semantic IDs like "net:request#__network__", (2) node.type is undefined
  but node.nodeType has a value, (3) metadata is a JSON string instead of parsed object,
  (4) tests fail with "Cannot read property 'length' of undefined" after queryNodes.
  Covers RFDBServerBackend vs RFDBClient distinction and async generator handling.
author: Claude Code
version: 1.0.0
date: 2025-01-22
---

# Grafema Test Backend Usage

## Problem

Tests querying the graph return malformed node data:
- IDs are internal numeric strings instead of human-readable semantic IDs
- `type` field is undefined (only `nodeType` is set)
- `metadata` is a raw JSON string instead of parsed object
- `originalId` and other metadata fields are missing from node

## Context / Trigger Conditions

1. Test uses `backend.client` to query nodes:
   ```javascript
   const graph = backend.client;  // WRONG
   const nodes = await collectNodes(graph.queryNodes({ type: 'net:request' }));
   ```

2. Node ID is numeric instead of semantic:
   ```
   Expected: "net:request#__network__"
   Actual: "52710336597754872375318185843222727675"
   ```

3. `node.type` is undefined but `node.nodeType` has the correct value

4. Using `await graph.queryNodes()` expecting an array (it's an async generator)

## Solution

### Issue 1: Use `backend` directly, not `backend.client`

```javascript
// WRONG - returns unparsed wire format
const graph = backend.client;

// CORRECT - returns parsed nodes with human-readable IDs
const graph = backend;
```

**Why**: `backend` is `RFDBServerBackend` which has `_parseNode()` that:
- Extracts `originalId` from metadata and uses it as the node's `id`
- Sets both `type` and `nodeType` from wire format
- Parses and spreads metadata fields onto the node object

`backend.client` is the raw `RFDBClient` which returns the wire format without parsing.

### Issue 2: Handle async generator properly

```javascript
// WRONG - queryNodes returns async generator, not Promise<array>
const nodes = await graph.queryNodes({ type: 'net:request' });
nodes.length;  // undefined - nodes is an async generator

// CORRECT - collect results into array
async function collectNodes(asyncGen) {
  const results = [];
  for await (const node of asyncGen) {
    results.push(node);
  }
  return results;
}

const nodes = await collectNodes(graph.queryNodes({ type: 'net:request' }));
nodes.length;  // works correctly
```

### Issue 3: Use correct edge query methods

```javascript
// WRONG - queryEdges doesn't exist
const edges = await graph.queryEdges({ type: 'CALLS', src: nodeId });

// CORRECT - use getOutgoingEdges or getIncomingEdges
const edges = await graph.getOutgoingEdges(nodeId, ['CALLS']);
```

## Verification

After fixing, verify nodes have correct structure:

```javascript
for await (const node of backend.queryNodes({ type: 'net:request' })) {
  console.log('ID:', node.id);           // Should be "net:request#__network__"
  console.log('type:', node.type);       // Should be "net:request"
  console.log('nodeType:', node.nodeType); // Should be "net:request"
  console.log('originalId:', node.originalId); // Should match id
}
```

## Example

Full test pattern:

```javascript
import { createTestBackend } from '../helpers/TestRFDB.js';

describe('My Test', () => {
  let backend;

  beforeEach(async () => {
    backend = createTestBackend();
    await backend.connect();  // Don't forget this!
  });

  afterEach(async () => {
    if (backend) await backend.close();
  });

  it('should find nodes correctly', async () => {
    // ... setup and analysis ...

    // Use backend directly, not backend.client
    const graph = backend;

    // Collect async generator results
    const nodes = [];
    for await (const node of graph.queryNodes({ type: 'net:request' })) {
      nodes.push(node);
    }

    // Now nodes is an array with properly parsed nodes
    assert.strictEqual(nodes[0].id, 'net:request#__network__');
    assert.strictEqual(nodes[0].type, 'net:request');
  });
});
```

## Notes

- `RFDBServerBackend._parseNode()` is responsible for the transformation
- The `originalId` is stored in the node's `metadata` JSON field in the database
- Both `type` and `nodeType` are set to the same value after parsing
- Edge methods (`getOutgoingEdges`, `getIncomingEdges`) return arrays, not generators
- Always call `backend.connect()` in `beforeEach` - the backend is not auto-connected
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall