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.
Grafema Test Backend Usage
Problem
Tests querying the graph return malformed node data:
- IDs are internal numeric strings instead of human-readable semantic IDs
typefield is undefined (onlynodeTypeis set)metadatais a raw JSON string instead of parsed objectoriginalIdand other metadata fields are missing from node
Context / Trigger Conditions
-
Test uses
backend.clientto query nodes:const graph = backend.client; // WRONG const nodes = await collectNodes(graph.queryNodes({ type: 'net:request' })); -
Node ID is numeric instead of semantic:
Expected: "net:request#__network__" Actual: "52710336597754872375318185843222727675" -
node.typeis undefined butnode.nodeTypehas the correct value -
Using
await graph.queryNodes()expecting an array (it's an async generator)
Solution
Issue 1: Use backend directly, not backend.client
// 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
originalIdfrom metadata and uses it as the node'sid - Sets both
typeandnodeTypefrom 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
// 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
// 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:
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:
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
originalIdis stored in the node'smetadataJSON field in the database - Both
typeandnodeTypeare set to the same value after parsing - Edge methods (
getOutgoingEdges,getIncomingEdges) return arrays, not generators - Always call
backend.connect()inbeforeEach- 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: 197k | Updated | Claude CodeCodex | Verified | Install |