Smoke Test

Gnapsis Smoke Test

Run through every gnapsis MCP tool to verify the system is functional. This skill exercises the full feature set: project setup, taxonomy, entity CRUD, references, search, subgraph queries, document analysis, validation, and multi-source support.

Prerequisites

1. Database must be running: just db-up
2. gnapsis must be installed: cargo install --path .
3. MCP server must be connected: /mcp

Test Procedure

Run each phase sequentially. If any step fails, jump to Phase 10 (Cleanup) to restore the original config before reporting the failure. Track entity IDs, reference IDs, and category IDs created during the test for cleanup.

Phase 0: Config Isolation

The smoke test uses a separate project name (gnapsis_smoke_test) so it gets its own graph and does not interfere with the real project data.

0.1 Backup the real config:

cp .gnapsis.toml .gnapsis.toml.bak

0.2 Overwrite .gnapsis.toml with the smoke test config:

# Force local database — overrides global ~/.config/gnapsis/config.toml
[postgres]
uri = "postgresql://postgres:postgres@localhost:5432/gnapsis_dev"

[embedding]
provider = "fastembed"
model = "BAAI/bge-small-en-v1.5"
dimensions = 384

[project]
name = "smoke_test"

[[project.sources]]
id = "default"
path = "<absolute path to this repo>"

[[project.sources]]
id = "vault"
path = "<absolute path to vault source from the backup>"

Copy the source paths from the backup file. The key differences are:

• [postgres] and [embedding] force the local Docker database (overrides global config)
• name = "smoke_test" creates graph gnapsis_smoke_test instead of gnapsis_gnapsis

0.3 Reconnect the MCP server so it picks up the new config: /mcp

Phase 1: Database Reset & Init

1.1 Drop the smoke test graph so init starts fresh:

just db-reset
just db-up

Wait for the database to be ready before proceeding.

1.2 Run init_project (force: true) and verify:

• Response includes db_version and graph_version
• applied_db_migrations is non-empty
• applied_graph_migrations is non-empty
• was_initialized is false (fresh graph)

1.3 Run init_project again (force: false) and verify:

• was_initialized is true
• applied_db_migrations is empty (no new migrations)
• applied_graph_migrations is empty

Phase 2: Project Overview (Empty State)

2.1 Run project_overview with no optional params and verify:

• categories contains 17 categories across 5 scopes (Domain, Feature, Namespace, Component, Unit)
• stats.domains is 0
• stats.features is 0
• stats.namespaces is 0
• stats.components is 0
• stats.units is 0
• stats.references is 0

2.2 Run project_overview with include_descriptions: true and verify:

• Response structure is the same
• Descriptions are not truncated

2.3 Run project_overview with output_format: "toon" and verify:

• Response is returned in TOON format

2.4 Note down the category IDs needed for entity creation:

• Find the "core" category at Domain scope -> save as DOMAIN_CAT_ID
• Find the "functional" category at Feature scope -> save as FEATURE_CAT_ID
• Find the "struct" category at Component scope -> save as COMPONENT_CAT_ID
• Find the "function" category at Unit scope -> save as UNIT_CAT_ID

Phase 3: Taxonomy

3.1 Run create_category with name "smoke-test", scope "Feature", description "Temporary category for smoke testing"

• Verify the category is created with an ID -> save as SMOKE_CAT_ID

3.2 Run project_overview and verify:

• The "smoke-test" category appears in the Feature scope
• Total category count is now 18

Phase 4: Entity CRUD

4A: Analyze Document (discover symbols)

4A.1 Run analyze_document on src/config.rs with source_id: "default" to discover symbols

• Verify untracked list contains symbols (e.g., "Config", "ProjectConfig", "Source")
• Save the untracked symbol names for use in entity creation

4B: Create Entity - Success Paths

4B.1 Create a Domain entity:

• name: "Smoke Test Domain"
• description: "Temporary domain for smoke testing gnapsis"
• category_ids: [DOMAIN_CAT_ID]
• commands: [Add code reference to src/config.rs, lsp_symbol "Config", source_id "default"]
• Verify: entity created with ID (save as DOMAIN_ID), has_embedding is true
• Verify: executed contains the Add command result with reference ID (save as DOMAIN_REF_ID)
• Verify: failed is null, skipped is empty

4B.2 Create a Feature entity with parent:

• name: "Smoke Test Feature"
• description: "Temporary feature for smoke testing"
• category_ids: [FEATURE_CAT_ID]
• parent_ids: [DOMAIN_ID]
• commands: [Add code reference to src/config.rs, lsp_symbol "ProjectConfig", source_id "default"]
• Verify: entity created with ID (save as FEATURE_ID), parent relationship established
• Verify: executed contains Add result with reference ID (save as FEATURE_REF_ID)

4B.3 Create a Component entity (child of Feature):

• name: "Smoke Test Component"
• description: "Temporary component for smoke testing"
• category_ids: [COMPONENT_CAT_ID]
• parent_ids: [FEATURE_ID]
• commands: [Add code reference to src/config.rs, lsp_symbol "Source", source_id "default"]
• Verify: entity created with ID (save as COMPONENT_ID)

4C: Create Entity - Error Paths

4C.1 Attempt to create entity with empty category_ids:

• Expect error about missing classification

4C.2 Attempt to create entity with a non-existent category ID:

• Expect error about invalid category

4C.3 Attempt to create entity with a non-existent parent ID:

• Expect error about invalid parent

4D: Update Entity - Success Paths

4D.1 Update the Feature entity description:

• entity_id: FEATURE_ID
• description: "Updated smoke test feature description"
• Verify: embedding_updated is true
• Verify: description changed in response

4D.2 Update entity with Relate command:

• entity_id: COMPONENT_ID
• commands: [Relate to DOMAIN_ID with note "smoke test relationship"]
• Verify: executed contains the Relate result

4D.3 Update entity with Unrelate command:

• entity_id: COMPONENT_ID
• commands: [Unrelate from DOMAIN_ID]
• Verify: relationship removed

4D.4 Update entity name only:

• entity_id: COMPONENT_ID
• name: "Renamed Smoke Component"
• Verify: name changed, embedding_updated is false (description unchanged)

4D.5 Update entity categories (replace semantics):

• entity_id: COMPONENT_ID
• category_ids: [COMPONENT_CAT_ID] (same category, verifies replace works)
• Verify: categories replaced

4E: Get Entity

4E.1 Run get_entity on DOMAIN_ID:

• Verify: returns full entity details with classifications, references, and hierarchy
• Verify: references include the code reference from 4B.1
• Verify: entity has parent/child relationships as expected

4F: Delete Entity - Error Paths

4F.1 Attempt to delete Domain entity (has children):

• entity_id: DOMAIN_ID
• Expect error: "has N children and cannot be deleted"

4G: Delete Entity - Success Path

4G.1 Delete the Component entity (leaf node):

• entity_id: COMPONENT_ID
• Verify: deleted is true

Phase 5: Multi-Source References

5.1 Create a Feature entity with a vault text reference:

• name: "Smoke Vault Feature"
• description: "Feature referencing vault documentation"
• category_ids: [FEATURE_CAT_ID]
• parent_ids: [DOMAIN_ID]
• commands: [Add text reference: source_id "vault", document_path "designs/005-ontology-improvements.md", start_line 1, end_line 30, anchor "# DES-005: Ontology Improvements"]
• Verify: entity created (save as VAULT_FEATURE_ID)
• Verify: executed contains Add with reference (save as VAULT_REF_ID)

5.2 Run get_entity on VAULT_FEATURE_ID:

• Verify: reference details include source_id: "vault"
• Verify: reference type is "text"
• Verify: document_path, start_line, end_line, anchor are correct

5.3 Create another entity with a code reference using default source_id:

• commands: [Add code reference without specifying source_id, document_path "src/config.rs", lsp_symbol "default_source_id"]
• Verify: reference created with source_id "default" (the default)

Phase 6: Search & Query

6A: Unified Search

6A.1 Search with target "entities":

• query: "smoke test domain"
• target: "entities"
• Verify: results contain entity matches
• Verify: references array is empty (target is entities-only)

6A.2 Search with target "references":

• query: "configuration"
• target: "references"
• Verify: results contain reference matches with document paths
• Verify: entities array is empty (target is references-only)

6A.3 Search with target "all" (default):

• query: "smoke testing"
• Verify: results may contain both entities and references

6A.4 Search with scope filter:

• query: "smoke"
• scope: "Domain"
• Verify: only Domain-scope entities returned

6A.5 Search with min_score filter:

• query: "smoke"
• min_score: 0.9
• Verify: only high-similarity results returned (may be empty)

6A.6 Search with limit:

• query: "smoke"
• limit: 1
• Verify: at most 1 result returned

6A.7 Search with output_format "toon":

• query: "smoke"
• output_format: "toon"
• Verify: response is in TOON format

6B: Semantic Subgraph Query

6B.1 Query with entity_id:

• entity_id: DOMAIN_ID
• Verify: nodes array contains the domain entity and connected entities
• Verify: edges array shows BELONGS_TO and HAS_REFERENCE relationships
• Verify: stats includes estimated_tokens and nodes_pruned

6B.2 Query with semantic_query only:

• semantic_query: "smoke test configuration"
• Verify: returns a subgraph relevant to the query

6B.3 Query with both entity_id and semantic_query:

• entity_id: DOMAIN_ID
• semantic_query: "configuration management"
• Verify: subgraph extracted with semantic relevance scoring

6B.4 Query with neither entity_id nor semantic_query:

• Expect error: "Either entity_id or semantic_query must be provided"

6B.5 Query with max_tokens limit:

• entity_id: DOMAIN_ID
• max_tokens: 500
• Verify: stats.estimated_tokens is within budget

6B.6 Query with max_nodes limit:

• entity_id: DOMAIN_ID
• max_nodes: 2
• Verify: at most 2 nodes returned

6B.7 Query with scoring_strategy "branch_penalty":

• entity_id: DOMAIN_ID
• scoring_strategy: "branch_penalty"
• Verify: response is valid (may differ from global strategy)

6B.8 Query with relationship_types filter:

• entity_id: DOMAIN_ID
• relationship_types: ["BELONGS_TO"]
• Verify: edges only contain BELONGS_TO relationships

6B.9 Query with output_format "toon":

• entity_id: DOMAIN_ID
• output_format: "toon"
• Verify: response is in TOON format

6C: Find Entities

6C.1 Find by scope:

• scope: "Domain"
• Verify: the smoke test domain entity appears in results

6C.2 Find by category:

• category: "core"
• Verify: domain entity appears

6C.3 Find by parent_id:

• parent_id: DOMAIN_ID
• Verify: the Feature and Vault Feature entities appear

6C.4 Find with limit:

• scope: "Feature"
• limit: 1
• Verify: at most 1 result

6C.5 Find with no filters:

• No scope, category, or parent_id
• Verify: returns all entities (up to default limit of 50)

6D: Get Document Entities

6D.1 Get entities for "src/config.rs" with source_id "default":

• Verify: entities with references to config.rs are listed
• Verify: reference details are included

6D.2 Get entities for a vault document:

• document_path: "designs/005-ontology-improvements.md"
• source_id: "vault"
• Verify: vault feature entity appears

Phase 7: Document Analysis

7.1 Run analyze_document on src/config.rs with source_id "default", all options enabled:

• include_tracked: true
• include_untracked: true
• include_diffs: true
• Verify: tracked references appear (from Phase 4)
• Verify: untracked symbols are listed
• Verify: source_id is "default" in response
• Verify: document_type is "code"
• Verify: summary has correct counts

7.2 Run analyze_document with only tracked references:

• include_tracked: true
• include_untracked: false
• include_diffs: false
• Verify: untracked is empty, diff_hunks is empty
• Verify: tracked is populated

7.3 Run analyze_document with only untracked symbols:

• include_tracked: false
• include_untracked: true
• include_diffs: false
• Verify: tracked is empty
• Verify: untracked is populated

7.4 Run analyze_document with explicit LSP symbols:

• Provide lsp_symbols array with at least one symbol (e.g., name "Config", kind 23, start_line and end_line from Phase 4A)
• Verify: untracked detection uses provided symbols

7.5 Run analyze_document with output_format "toon":

• Verify: response is in TOON format

7.6 Run analyze_document on a vault document:

• document_path: "designs/005-ontology-improvements.md"
• source_id: "vault"
• Verify: responds without error
• Verify: document_type is "text"
• Verify: tracked references from Phase 5 appear (if any)

Phase 8: Reference Management

8A: Get Changed Files

8A.1 Run get_changed_files with no params:

• Verify: returns a list of changed files with change types
• Verify: response includes file paths

8A.2 Run get_changed_files with from_sha and to_sha (use HEAD~1 and HEAD):

• First get HEAD SHA via git
• Verify: returns files changed in the last commit

8B: Alter References - Update

8B.1 Run alter_references with an Update command on FEATURE_REF_ID:

• Update start_line to a new value (e.g., 10)
• Update end_line to a new value (e.g., 50)
• Verify: update succeeds
• Verify: response shows the updated reference

8B.2 Run alter_references with Update on text reference VAULT_REF_ID:

• Update anchor to "# Updated Anchor"
• Verify: anchor updated

8C: Alter References - Delete

8C.1 Attempt to delete a reference that is attached to an entity:

• Run alter_references with Delete on FEATURE_REF_ID
• Expect error: reference is attached to an entity

8C.2 To test delete success: first create a standalone reference, detach it, then delete:

• Create a temporary entity with a reference
• Use update_entity with Unattach command to detach the reference
• Run alter_references with Delete on the detached reference
• Verify: deletion succeeds
• Clean up the temporary entity

8D: LSP Refresh

8D.1 Run lsp_refresh on src/config.rs with source_id "default":

• Provide LSP symbols from analyze_document (Phase 7.1) untracked list
• Include at least the symbols that have existing references (e.g., "Config", "ProjectConfig")
• Verify: updated_count shows how many references were refreshed
• Verify: updated array shows old and new line numbers for changed refs
• Verify: unmatched_count shows symbols with no matching reference

Phase 9: Graph Validation

9.1 Run validate_graph with all checks enabled:

• check_orphans: true
• check_cycles: true
• check_scope_violations: true
• check_unclassified: true
• check_no_references: true
• Verify: valid is true or only has expected issues from test data
• Verify: issue_count matches the sum of all issue arrays

9.2 Run validate_graph with only orphan check:

• check_orphans: true
• check_cycles: false
• check_scope_violations: false
• check_unclassified: false
• check_no_references: false
• Verify: only orphans array may have entries, all others are empty

9.3 Run validate_graph with only cycle check:

• check_cycles: true, all others false
• Verify: cycles is empty (no cycles in test data)

9.4 Run validate_graph with only scope violations check:

• check_scope_violations: true, all others false
• Verify: no scope violations in test data

Phase 10: Cleanup

This phase MUST run even if a previous phase failed — it restores the original config.

10.1 Delete entities in reverse dependency order:

• Delete VAULT_FEATURE_ID (and any temp entities from Phase 8C)
• Delete FEATURE_ID
• Delete DOMAIN_ID
• Verify: each deletion succeeds

10.2 Run project_overview and verify:

• stats.domains is 0
• stats.features is 0
• stats.components is 0
• stats.references is 0

10.3 Drop the smoke test graph to leave no residue:

# The graph gnapsis_smoke_test can be dropped via psql or left for next run
# init_project with force:true will recreate it anyway

10.4 Restore the original config:

mv .gnapsis.toml.bak .gnapsis.toml

10.5 Reconnect the MCP server to restore the real project config: /mcp

10.6 Report: "Smoke test PASSED - all 10 phases completed successfully"

Failure Reporting

If any phase fails:

1. Always run Phase 10.4 and 10.5 first to restore the original config
2. Then report:
   • Phase number and subtest that failed (e.g., "Phase 4, Test 4C.1")
   • Tool name and parameters used
   • Error message received
   • "Smoke test FAILED at Phase N, Test N.X"

Notes

• The vault source path is configured in .gnapsis.toml under [[project.sources]]
• All sources share the same graph: gnapsis_<project_name>
• References store source_id to track which source they belong to
• If vault source is not configured, skip Phase 5 and vault-related steps in Phases 6-7
• Entity IDs, reference IDs, and category IDs should be tracked throughout the test for assertions and cleanup
• Error path tests (e.g., 4C, 6B.4, 8C.1) expect specific errors - verify the error message matches

Converted and distributed by TomeVault — claim your Tome and manage your conversions.