Testing Strategies | Geode Database

Geode maintains comprehensive test coverage across multiple testing frameworks ensuring production readiness with 97.4% integration test pass rate (1644/1688 tests) and 100% unit test pass rate (393/393 tests). This guide covers all testing strategies, frameworks, and best practices for developing robust graph database applications. <h3 id="test-coverage-overview" class="position-relative d-flex align-items-center group"> Test Coverage Overview <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="test-coverage-overview" aria-haspopup="dialog" aria-label="Share link: Test Coverage Overview"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script> <h4 id="current-test-status" class="position-relative d-flex align-items-center group"> Current Test Status <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="current-test-status" aria-haspopup="dialog" aria-label="Share link: Current Test Status"> Share link </button> </h4>Integration Tests (geodetestlab): <ul> <li>Pass Rate: 97.4% (1644/1688 tests passing)</li> <li>Total Tests: 1688 comprehensive integration scenarios</li> <li>Skipped Tests: ~120 (intentionally skipped due to documented limitations)</li> <li>Coverage: Authentication, user management, query execution, CLI commands</li> </ul> Unit Tests (Zig): <ul> <li>Pass Rate: 100% (393/393 tests passing)</li> <li>Coverage: All core modules with comprehensive test blocks</li> <li>CANARY Integration: 1,735 governance markers tracking 2,190+ requirements</li> </ul> GQL Conformance: <ul> <li>ISO/IEC 39075:2024: 100% compliance (see conformance profile)</li> <li>Scope: Conformance and diagnostics documented in the profile</li> </ul> <h3 id="testing-frameworks" class="position-relative d-flex align-items-center group"> Testing Frameworks <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="testing-frameworks" aria-haspopup="dialog" aria-label="Share link: Testing Frameworks"> Share link </button> </h3> <h4 id="1-zig-unit-tests" class="position-relative d-flex align-items-center group"> 1. Zig Unit Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="1-zig-unit-tests" aria-haspopup="dialog" aria-label="Share link: 1. Zig Unit Tests"> Share link </button> </h4>Native Zig unit testing framework for component-level testing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const std = @import("std"); const testing = std.testing; test "basic query parsing" { // Setup const allocator = std.testing.allocator; const parser = @import("../src/gql/parser.zig"); // Execute const result = try parser.parse(allocator, "RETURN 1 AS x"); defer result.deinit(allocator); // Verify try testing.expectEqual(1, result.program.statements.len); } </code></pre></div>Run Unit Tests: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># All unit tests make test # Specific module zig test src/gql/parser.zig # With verbose output zig test src/gql/parser.zig --test-verbose </code></pre></div>Coverage Areas: <ul> <li>Parser and lexer validation</li> <li>Query planner logic</li> <li>Storage engine operations</li> <li>Index implementations</li> <li>Security and authentication</li> <li>Transaction management</li> </ul> <h4 id="2-geodetestlab-integration-tests" class="position-relative d-flex align-items-center group"> 2. geodetestlab Integration Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="2-geodetestlab-integration-tests" aria-haspopup="dialog" aria-label="Share link: 2. geodetestlab Integration Tests"> Share link </button> </h4>Python-based YAML specification framework for end-to-end testing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># geodetestlab/specs/basic_queries.yml name: "basic-query-tests" tests: - name: "simple-return" args: ["query", "RETURN 1 AS x"] expect: exit_code: 0 stdout_json_assert: - path: "result.rows[0].x" equals: 1 </code></pre></div>Run Integration Tests: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># All geodetestlab tests python3 scripts/test/extended_test_runner.py # Specific spec file python3 scripts/test/extended_test_runner.py --specs geodetestlab/specs/basic_queries.yml # With verbose output python3 scripts/test/extended_test_runner.py --verbose </code></pre></div>Variable Substitution: <ul> <li><code>${server}</code> → <code>127.0.0.1:3141</code></li> <li><code>${server:host}</code> → <code>127.0.0.1</code></li> <li><code>${server:port}</code> → <code>3141</code></li> <li><code>${secret:api_token}</code> → Test token</li> <li><code>${secret:user_password}</code> → Test password</li> </ul> Test Specification Format: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">name: "feature-tests" tests: - name: "test-case" args: ["command", "--flag", "value"] expect: exit_code: 0 stdout_contains: ["Success"] stderr_contains: [] stdout_regex: ["Result.*complete"] stdout_json_assert: - path: "status" equals: "00000" </code></pre></div> <h4 id="3-shell-based-regression-tests" class="position-relative d-flex align-items-center group"> 3. Shell-Based Regression Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="3-shell-based-regression-tests" aria-haspopup="dialog" aria-label="Share link: 3. Shell-Based Regression Tests"> Share link </button> </h4>Bash scripts for comprehensive regression testing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">#!/bin/bash # tests/limit_skip_regression_test.sh set -e # Setup ./setup_test_env.sh # Test: LIMIT and SKIP result=$(./geode query "MATCH (n:Person) RETURN n.name ORDER BY n.name LIMIT 10 SKIP 5") # Verify if [ $(echo "$result" | jq '.result.rows | length') -ne 10 ]; then echo "FAIL: Expected 10 rows" exit 1 fi echo "PASS: LIMIT/SKIP regression test" </code></pre></div>Regression Test Suites: <ul> <li><code>comprehensive_regression_test.sh</code>: 34 scenarios</li> <li><code>limit_skip_regression_test.sh</code>: 23 scenarios</li> <li><code>property_ordering_regression_test.sh</code>: 10 scenarios</li> <li><code>count_aggregation_regression_test.sh</code>: 8 scenarios</li> </ul> Run Regression Tests: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># All regression tests ./tests/comprehensive_regression_test.sh ./tests/limit_skip_regression_test.sh ./tests/property_ordering_regression_test.sh ./tests/count_aggregation_regression_test.sh # Or use make target make regression-test </code></pre></div> <h4 id="4-module-testing-framework" class="position-relative d-flex align-items-center group"> 4. Module Testing Framework <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="4-module-testing-framework" aria-haspopup="dialog" aria-label="Share link: 4. Module Testing Framework"> Share link </button> </h4>Isolated module testing with dependency injection: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const framework = @import("module_test_framework.zig"); test "schema_manager with dependency injection" { // Test allocator for leak detection var test_alloc = framework.TestAllocator.init(); defer test_alloc.deinit() catch unreachable; const allocator = test_alloc.allocator(); // Create dependency container var deps = framework.DependencyContainer(void).init(allocator); defer deps.deinit(); // Register mock filesystem var mock_fs = framework.MockFileSystem.init(allocator); defer mock_fs.deinit(); try deps.register("filesystem", @ptrCast(&mock_fs)); // Test module with injected dependencies const schema = @import("../src/schema/schema_manager.zig"); var manager = try schema.SchemaManager.init(allocator, "/tmp/test"); defer manager.deinit(); // Verify operations try manager.createSchema("test_schema"); try testing.expect(manager.schemaExists("test_schema")); } </code></pre></div>Mock I/O Interfaces: MockFileSystem: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">var mock_fs = framework.MockFileSystem.init(allocator); defer mock_fs.deinit(); // Mock file operations try mock_fs.writeFile("/path/to/file", "content"); const content = try mock_fs.readFile("/path/to/file"); // Verify operations try framework.Assertions.expectCallCount(1, mock_fs.write_calls, "writeFile"); </code></pre></div>MockNetwork: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">var mock_net = framework.MockNetwork.init(allocator); defer mock_net.deinit(); // Queue received message try mock_net.queueReceive("HELLO{\"client\":\"test\"}"); // Process message const request = try mock_net.receive(); // Send response try mock_net.send("OK{\"status\":\"connected\"}"); // Verify try framework.Assertions.expectCallCount(1, mock_net.send_calls, "send"); </code></pre></div>MockStorage: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">var mock_storage = framework.MockStorage.init(allocator); defer mock_storage.deinit(); // Mock storage operations try mock_storage.write("node:1", "{\"id\":1,\"label\":\"Person\"}"); const data = try mock_storage.read("node:1"); try mock_storage.delete("node:1"); // Verify call counts try framework.Assertions.expectCallCount(1, mock_storage.write_calls, "write"); try framework.Assertions.expectCallCount(1, mock_storage.read_calls, "read"); try framework.Assertions.expectCallCount(1, mock_storage.delete_calls, "delete"); </code></pre></div> <h4 id="5-fuzz-testing" class="position-relative d-flex align-items-center group"> 5. Fuzz Testing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="5-fuzz-testing" aria-haspopup="dialog" aria-label="Share link: 5. Fuzz Testing"> Share link </button> </h4>Deterministic fuzz testing for parser, planner, and storage: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Run fuzz tests make fuzz # Fuzz specific component zig test fuzz/parser_fuzz.zig # With custom seed for reproducibility FUZZ_SEED=12345 make fuzz </code></pre></div>Fuzz Test Components: <ul> <li>Parser Fuzzing: Random GQL queries with deterministic seeds</li> <li>Planner Fuzzing: Query plan variations</li> <li>Storage Fuzzing: Random data patterns</li> </ul> Example Fuzz Test: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">test "fuzz parser with random queries" { const allocator = std.testing.allocator; const parser = @import("../src/gql/parser.zig"); var prng = std.rand.DefaultPrng.init(12345); const random = prng.random(); var i: u32 = 0; while (i < 1000) : (i += 1) { const query = try generateRandomQuery(allocator, random); defer allocator.free(query); // Should not crash (may fail to parse) const result = parser.parse(allocator, query) catch continue; defer result.deinit(allocator); } } </code></pre></div> <h4 id="6-performance-benchmarking" class="position-relative d-flex align-items-center group"> 6. Performance Benchmarking <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="6-performance-benchmarking" aria-haspopup="dialog" aria-label="Share link: 6. Performance Benchmarking"> Share link </button> </h4>Automated performance regression testing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Run benchmarks make bench # Specific benchmark zig test benchmark/query_performance.zig # Compare with baseline make bench-compare </code></pre></div>Benchmark Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">test "benchmark: simple query performance" { const allocator = std.testing.allocator; const start = std.time.nanoTimestamp(); var i: u32 = 0; while (i < 10000) : (i += 1) { const result = try executeQuery(allocator, "RETURN 1 AS x"); defer result.deinit(allocator); } const end = std.time.nanoTimestamp(); const duration_ms = @divTrunc(end - start, std.time.ns_per_ms); std.debug.print("10,000 queries in {} ms ({} queries/sec)\n", .{ duration_ms, @divTrunc(10000 * 1000, duration_ms), }); // Assert performance threshold try testing.expect(duration_ms < 5000); // < 5 seconds } </code></pre></div>Tracked Metrics: <ul> <li>Query execution time</li> <li>Index lookup performance</li> <li>Transaction throughput</li> <li>Memory allocation patterns</li> <li>Network I/O latency</li> </ul> <h3 id="dataset-integration-testing" class="position-relative d-flex align-items-center group"> Dataset Integration Testing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="dataset-integration-testing" aria-haspopup="dialog" aria-label="Share link: Dataset Integration Testing"> Share link </button> </h3>Test with realistic datasets for production scenarios: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Load test datasets make load-dataset # Run dataset integration tests make dataset-integration-test </code></pre></div>Available Datasets: Social Network: <ul> <li>10,000+ users with profiles</li> <li>50,000+ posts and comments</li> <li>25,000+ groups and events</li> <li>100,000+ relationships (FOLLOWS, LIKES, MEMBER_OF)</li> </ul> IoT Network: <ul> <li>25,000+ devices (sensors, gateways, controllers)</li> <li>100,000+ telemetry readings</li> <li>Device hierarchies and connectivity</li> </ul> Financial Network: <ul> <li>50,000 accounts (users, merchants, banks)</li> <li>250,000 transactions</li> <li>Fraud detection patterns</li> </ul> Geographic Data: <ul> <li>100 cities with coordinates</li> <li>25,000 points of interest (restaurants, shops, landmarks)</li> <li>Spatial relationships</li> </ul> Dataset Test Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Query social network dataset MATCH (u:User)-[:FOLLOWS]->(friend:User) WHERE u.id = 123 RETURN friend.name, friend.follower_count ORDER BY friend.follower_count DESC LIMIT 10; -- Expected: 10 most popular friends of user 123 -- Verify: Result count, ordering, data integrity </code></pre></div> <h3 id="canary-system-integration" class="position-relative d-flex align-items-center group"> CANARY System Integration <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="canary-system-integration" aria-haspopup="dialog" aria-label="Share link: CANARY System Integration"> Share link </button> </h3>Link tests to requirements for governance tracking: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// CANARY: REQ=REQ-XXX; FEATURE="BasicQuery"; ASPECT=Testing; STATUS=TESTED; TEST=TestBasicQuery; OWNER=test; UPDATED=2026-01-24 test "TestCANARY_REQ_GQL_001_BasicQuery" { const allocator = std.testing.allocator; const parser = @import("../src/gql/parser.zig"); const result = try parser.parse(allocator, "RETURN 1 AS x"); defer result.deinit(allocator); try testing.expectEqual(1, result.program.statements.len); } </code></pre></div>CANARY Status Values: <ul> <li><code>TESTED</code>: Automated test coverage</li> <li><code>BENCHED</code>: Performance benchmark exists</li> <li><code>IMPL</code>: Implementation complete</li> <li><code>EXEMPT</code>: Explicitly excluded from testing</li> </ul> Generate CANARY Report: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Update governance status make status-generate # View status breakdown cat docs/status.csv </code></pre></div>Current CANARY Status: <ul> <li>Total Markers: 1,735 tracking 2,190+ requirements</li> <li>TESTED: 81.4%</li> <li>BENCHED: 6.0%</li> <li>IMPL: 7.7%</li> <li>EXEMPT: 5.7%</li> </ul> <h3 id="cicd-integration" class="position-relative d-flex align-items-center group"> CI/CD Integration <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="cicd-integration" aria-haspopup="dialog" aria-label="Share link: CI/CD Integration"> Share link </button> </h3> <h4 id="gitlab-ci-pipeline" class="position-relative d-flex align-items-center group"> GitLab CI Pipeline <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="gitlab-ci-pipeline" aria-haspopup="dialog" aria-label="Share link: GitLab CI Pipeline"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># .gitlab-ci.yml stages: - build - test - benchmark - governance build: stage: build script: - make build test-unit: stage: test script: - make test - make geodetestlab-comprehensive benchmark: stage: benchmark script: - make bench - make bench-compare governance-check: stage: governance script: - make status-generate - diff docs/status.csv /tmp/status_check.csv </code></pre></div>Run CI Locally: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Full CI pipeline make ci # Individual stages make build make test make bench make status-generate </code></pre></div> <h4 id="docker-testing" class="position-relative d-flex align-items-center group"> Docker Testing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="docker-testing" aria-haspopup="dialog" aria-label="Share link: Docker Testing"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Run tests in Docker make docker-test # Full CI pipeline in Docker make docker-ci # Docker compose testing make docker-up-singleton make docker-test make docker-down </code></pre></div> <h3 id="test-development-guidelines" class="position-relative d-flex align-items-center group"> Test Development Guidelines <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="test-development-guidelines" aria-haspopup="dialog" aria-label="Share link: Test Development Guidelines"> Share link </button> </h3> <h4 id="writing-unit-tests" class="position-relative d-flex align-items-center group"> Writing Unit Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="writing-unit-tests" aria-haspopup="dialog" aria-label="Share link: Writing Unit Tests"> Share link </button> </h4>Follow Test Structure: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">test "component: specific behavior" { // 1. Setup const allocator = std.testing.allocator; // 2. Execute const result = try functionUnderTest(allocator, input); defer result.deinit(allocator); // 3. Verify try testing.expectEqual(expected, result.value); try testing.expect(result.is_valid); // 4. Cleanup (via defer) } </code></pre></div>Naming Conventions: <ul> <li><code>test "module_name: behavior description"</code></li> <li><code>test "TestCANARY_REQ_ID_FeatureName"</code> (for CANARY-tracked tests)</li> </ul> Best Practices: <ul> <li>Use <code>std.testing.allocator</code> for automatic leak detection</li> <li>Always <code>defer</code> cleanup operations</li> <li>Test both success and error paths</li> <li>Verify edge cases and boundary conditions</li> </ul> <h4 id="writing-integration-tests" class="position-relative d-flex align-items-center group"> Writing Integration Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="writing-integration-tests" aria-haspopup="dialog" aria-label="Share link: Writing Integration Tests"> Share link </button> </h4>YAML Specification: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">name: "feature-integration-tests" setup: - args: ["user", "create", "test_user", "--password", "test123"] expect: exit_code: 0 tests: - name: "feature-basic-operation" args: ["command", "--option", "value"] expect: exit_code: 0 stdout_contains: ["Success"] stdout_json_assert: - path: "result.status" equals: "completed" teardown: - args: ["user", "delete", "test_user"] expect: exit_code: 0 </code></pre></div>JSON Assertions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">stdout_json_assert: # Check value equality - path: "result.count" equals: 5 # Check type - path: "result.items" type: "array" # Check array length - path: "result.items" array_length: 3 # Check nested path - path: "result.user.roles[0]" equals: "admin" </code></pre></div> <h4 id="writing-regression-tests" class="position-relative d-flex align-items-center group"> Writing Regression Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="writing-regression-tests" aria-haspopup="dialog" aria-label="Share link: Writing Regression Tests"> Share link </button> </h4>Shell Script Template: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">#!/bin/bash set -e # Metadata TEST_NAME="feature_regression_test" DESCRIPTION="Test for regression in specific feature" # Setup source ./tests/common.sh setup_test_env # Test cases echo "Test 1: Basic functionality" result=$(./geode query "RETURN 1 AS x") assert_equals "1" "$(echo "$result" | jq -r '.result.rows[0].x')" echo "Test 2: Edge case" result=$(./geode query "RETURN null AS x") assert_null "$(echo "$result" | jq -r '.result.rows[0].x')" # Cleanup cleanup_test_env echo "PASS: $TEST_NAME" </code></pre></div>Common Functions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># tests/common.sh assert_equals() { if [ "$1" != "$2" ]; then echo "FAIL: Expected '$1', got '$2'" exit 1 fi } assert_null() { if [ "$1" != "null" ]; then echo "FAIL: Expected null, got '$1'" exit 1 fi } setup_test_env() { # Create temporary data directory export TEST_DATA_DIR=$(mktemp -d) # Start test server ./geode serve --data-dir "$TEST_DATA_DIR" --listen 127.0.0.1:3141 & SERVER_PID=$! sleep 2 } cleanup_test_env() { # Stop server kill $SERVER_PID # Remove temporary data rm -rf "$TEST_DATA_DIR" } </code></pre></div> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3> <h4 id="test-isolation" class="position-relative d-flex align-items-center group"> Test Isolation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="test-isolation" aria-haspopup="dialog" aria-label="Share link: Test Isolation"> Share link </button> </h4>Ensure tests don’t interfere with each other: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Use isolated data directories for each test export GEODE_DATA_DIR=/tmp/test-$RANDOM # Clean up after tests cleanup() { rm -rf "$GEODE_DATA_DIR" } trap cleanup EXIT </code></pre></div> <h4 id="memory-leak-detection" class="position-relative d-flex align-items-center group"> Memory Leak Detection <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="memory-leak-detection" aria-haspopup="dialog" aria-label="Share link: Memory Leak Detection"> Share link </button> </h4>Use <code>std.testing.allocator</code> for automatic leak detection: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">test "no memory leaks" { const allocator = std.testing.allocator; const data = try allocator.alloc(u8, 1024); defer allocator.free(data); // Will fail test if missing // Use data } </code></pre></div> <h4 id="error-path-testing" class="position-relative d-flex align-items-center group"> Error Path Testing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-path-testing" aria-haspopup="dialog" aria-label="Share link: Error Path Testing"> Share link </button> </h4>Test error conditions explicitly: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">test "error handling: invalid input" { const allocator = std.testing.allocator; // Should return error try testing.expectError( error.InvalidInput, functionUnderTest(allocator, invalid_input) ); } </code></pre></div> <h4 id="performance-assertions" class="position-relative d-flex align-items-center group"> Performance Assertions <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-assertions" aria-haspopup="dialog" aria-label="Share link: Performance Assertions"> Share link </button> </h4>Assert performance thresholds in benchmarks: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">test "benchmark: query performance threshold" { const start = std.time.nanoTimestamp(); // Execute operation _ = try executeQuery(allocator, "RETURN 1 AS x"); const end = std.time.nanoTimestamp(); const duration_us = @divTrunc(end - start, std.time.ns_per_us); // Assert < 1ms try testing.expect(duration_us < 1000); } </code></pre></div> <h3 id="debugging-failed-tests" class="position-relative d-flex align-items-center group"> Debugging Failed Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="debugging-failed-tests" aria-haspopup="dialog" aria-label="Share link: Debugging Failed Tests"> Share link </button> </h3> <h4 id="enable-verbose-output" class="position-relative d-flex align-items-center group"> Enable Verbose Output <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="enable-verbose-output" aria-haspopup="dialog" aria-label="Share link: Enable Verbose Output"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Verbose geodetestlab tests python3 scripts/test/extended_test_runner.py --verbose # Verbose Zig tests zig test src/module.zig --test-verbose # Debug CLI commands GEODE_DEBUG=1 ./geode command </code></pre></div> <h4 id="check-server-logs" class="position-relative d-flex align-items-center group"> Check Server Logs <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="check-server-logs" aria-haspopup="dialog" aria-label="Share link: Check Server Logs"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># JSON logging for structured output ./geode serve --log_json # Capture server stderr ./geode serve 2> server_errors.log </code></pre></div> <h4 id="isolated-test-execution" class="position-relative d-flex align-items-center group"> Isolated Test Execution <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="isolated-test-execution" aria-haspopup="dialog" aria-label="Share link: Isolated Test Execution"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Run single geodetestlab test python3 scripts/test/extended_test_runner.py --specs geodetestlab/specs/file.yml --test specific-test-name # Run single Zig test zig test src/module.zig --test-filter "test name" </code></pre></div> <h3 id="related-documentation" class="position-relative d-flex align-items-center group"> Related Documentation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-documentation" aria-haspopup="dialog" aria-label="Share link: Related Documentation"> Share link </button> </h3><ul> <li><a href="/docs/configuration/server-configuration/" >Server Configuration</a> - Configure test environments</li> <li><a href="/docs/guides/troubleshooting/" >Troubleshooting Guide</a> - Debug test failures</li> <li><a href="/docs/query/performance-tuning/" >Query Performance Tuning</a> - Optimize test performance</li> <li><a href="/docs/transactions/advanced-patterns/" >Advanced Transaction Patterns</a> - Test transaction scenarios</li> </ul> <h3 id="summary" class="position-relative d-flex align-items-center group"> Summary <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="summary" aria-haspopup="dialog" aria-label="Share link: Summary"> Share link </button> </h3>Geode provides comprehensive testing infrastructure: <ul> <li>Unit Tests: 100% pass rate (393/393) with Zig framework</li> <li>Integration Tests: 97.4% pass rate (1644/1688) with geodetestlab</li> <li>Regression Tests: 75+ scenarios across 4 test suites</li> <li>Module Testing: Dependency injection and mock I/O interfaces</li> <li>Fuzz Testing: Deterministic fuzzing for parser, planner, storage</li> <li>Performance Benchmarking: Automated regression detection</li> <li>CI/CD Integration: GitLab CI, Docker</li> <li>CANARY Tracking: 1,735 governance markers tracking 2,190+ requirements</li> </ul> Use appropriate testing strategies based on component type: unit tests for isolated logic, integration tests for end-to-end scenarios, regression tests for bug prevention, and benchmarks for performance validation. Maintain test isolation, check for memory leaks, and test error paths explicitly.