Disentinel/grafema / .claude/skills/grafema-test-backend-usage
grafema-test-backend-usage
VerifiedFix 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
SKILL.md
View on GitHub---
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |