Skip to content
Codex
Documentation GitHub
Workspace

Import System

Import System

Covers the full import flow for bringing external markdown content into Inklings through the app’s import dialog. The user selects a source folder, reviews the preview analysis, chooses a conflict strategy, confirms the import, and observes the result in the sidebar. Tests verify what is visible and interactive in the UI rather than API response shapes.

Import operations create a new workspace from the source content. Each scenario should use a distinct source folder to avoid collisions between test runs.

Preconditions

  • The app is open and at least one workspace is loaded
  • Test fixture directories exist on the local filesystem at known paths (see Test Data section)
  • The fixture directories must NOT contain an inklings.db file (the app rejects such folders)

Scenarios

Seed: seed.spec.ts

1. Detect source type — plain markdown folder shows “Markdown Folder” in the import dialog

Open the import dialog and select a folder containing .md files but no .obsidian directory. Verify the dialog identifies the source type correctly.

Steps:

  1. Open the Import dialog (via the File menu or the sidebar import action).
  2. Select or enter the path to the plain markdown fixture folder.
  3. Observe the source type label displayed in the dialog.

Expected: The dialog displays the source type as “Markdown Folder” (or equivalent label). No error or warning is shown. The dialog proceeds to the preview step.

2. Detect source type — Obsidian vault shows “Obsidian Vault” in the import dialog

Open the import dialog and select a folder that contains a .obsidian subdirectory. Verify the dialog identifies it as an Obsidian vault.

Steps:

  1. Open the Import dialog.
  2. Select or enter the path to the Obsidian fixture vault.
  3. Observe the source type label displayed in the dialog.

Expected: The dialog displays the source type as “Obsidian Vault” (or equivalent label). The preview step becomes available.

3. Analyze import preview — file and folder counts are shown for a markdown folder

After selecting a markdown fixture folder in the import dialog, the preview panel should display the number of files and folders found.

Steps:

  1. Open the Import dialog.
  2. Select the markdown fixture folder.
  3. Wait for the preview panel to load.
  4. Observe the file count and folder count displayed in the preview.

Expected: The preview panel shows a file count of at least 1 and a folder count of at least 0. The source folder name appears as the preview title. The source type label reads “Markdown Folder”.

4. Analyze import preview — Obsidian vault shows wiki-link count in the preview

When an Obsidian vault containing [[wiki-link]] syntax is selected, the import preview should report the number of wiki links that will be converted.

Steps:

  1. Open the Import dialog.
  2. Select the Obsidian fixture vault (which contains at least two pages with [[PageName]] links).
  3. Wait for the preview panel to load.
  4. Observe the wiki-link count displayed in the preview.

Expected: The preview panel shows a wiki-link conversion count of at least 1. The source type label reads “Obsidian Vault”.

5. Execute import — basic markdown folder completes and pages appear in sidebar

Select a small markdown fixture folder, configure the workspace, confirm the import, and verify the imported pages are visible in the sidebar.

Steps:

  1. Open the Import dialog.
  2. Select the markdown fixture folder.
  3. Enter a workspace name and target location.
  4. Review the preview (source type “Markdown Folder”, file count >= 1).
  5. Click “Import” (or “Confirm”) to start the import.
  6. Wait for the import to complete (the dialog closes or a completion indicator appears).
  7. Observe the sidebar page list.

Expected: At least one new page appears in the sidebar. The workspace name matches the configured name. No error message is displayed.

bridge:partial — No import progress steps are shown during the import. The UI moves directly from “Importing…” to the completion state. The test cannot assert intermediate phase transitions (Analyzing → Copying → Indexing → Complete).

6. Execute import — hierarchy preservation shows nested pages in sidebar

Import a fixture folder with a nested subdirectory structure and verify the page tree in the sidebar mirrors the folder hierarchy.

Steps:

  1. Open the Import dialog.
  2. Select the nested hierarchy fixture folder (which has parent/child/grandchild.md).
  3. Confirm the import with default settings.
  4. Wait for completion.
  5. Expand the page tree in the sidebar to reveal nested pages.

Expected: The sidebar shows a parent page containing a child page, which in turn contains “grandchild” as a nested page. The nesting depth and order matches the source folder structure.

bridge:partial — No progress events are shown. Hierarchy is visible in the sidebar after the import completes.

7. Execute import — Obsidian wiki-link conversion results in linked pages

Import an Obsidian fixture vault where one page links to another via [[PageName]] syntax. After import, the linked page should be reachable via the converted link.

Steps:

  1. Open the Import dialog.
  2. Select the Obsidian fixture vault (which has alpha.md containing [[Beta]] and beta.md).
  3. Confirm the import.
  4. Wait for completion.
  5. Open the “alpha” page in the editor.
  6. Observe whether the [[Beta]] reference appears as a resolved wiki-link (not a ghost/broken link).
  7. Click the wiki-link and verify it navigates to the “beta” page.

Expected: The wiki-link in “alpha” resolves to “beta” and navigates successfully. No ghost-link styling is visible on the resolved link.

bridge:partial — No progress events. Wiki-link conversion is validated by observing the rendered link state in the editor.

8. Execute import — duplicate slug conflict with Skip strategy leaves existing page unchanged

When the workspace already contains a page with the same slug as an imported file, the Skip conflict strategy should leave the existing page untouched and report the skipped item.

Steps:

  1. Ensure the current workspace has a page with title “Hero” (slug hero).
  2. Open the Import dialog.
  3. Select the fixture folder containing hero.md.
  4. In the conflict strategy selector, choose “Skip” (or accept the default).
  5. Confirm the import.
  6. After completion, observe the import summary shown in the dialog or notification.
  7. Open the “Hero” page and verify its content has not changed.

Expected: The import summary shows at least 1 skipped file. The “Hero” page in the workspace retains its original content. No error is displayed.

9. Execute import — duplicate slug conflict with Rename strategy creates a renamed page

Same setup as scenario 8, but selecting the “Rename” conflict strategy should import the conflicting file under a suffixed name.

Steps:

  1. Ensure the workspace has a page with slug hero.
  2. Open the Import dialog.
  3. Select the fixture folder containing hero.md.
  4. In the conflict strategy selector, choose “Rename”.
  5. Confirm the import.
  6. After completion, observe the sidebar for a new page with a name like “Hero (1)” or “hero-1”.

Expected: A new page with a renamed slug (e.g., hero-1) appears in the sidebar. The original “Hero” page is unchanged. The import summary shows 0 skipped files and at least 1 imported file.

10. Validate import path — non-existent path shows an error in the dialog

Attempt to enter a path that does not exist on the filesystem in the import dialog. The dialog should display a validation error rather than proceeding to the preview.

Steps:

  1. Open the Import dialog.
  2. Manually type or paste a path that does not exist (e.g., /tmp/does-not-exist-sentinel-qa).
  3. Attempt to proceed to the next step.

Expected: The dialog displays a validation error indicating the path does not exist. The preview step is not shown. No import is started.

11. Validate import path — selecting a file instead of a directory shows an error

Attempt to select a single file (not a directory) as the import source. The dialog should reject this and display an appropriate error.

Steps:

  1. Open the Import dialog.
  2. Use the file picker to navigate to and select a single file (not a folder).
  3. Observe the dialog state.

Expected: The dialog displays a validation error indicating that a directory must be selected. The preview step does not appear.

12. Validate import path — existing Inklings workspace folder is rejected with an explanation

Attempt to import a folder that already contains an inklings.db file (an existing Inklings workspace). The dialog should reject it with an explanation telling the user to open the workspace instead.

Steps:

  1. Open the Import dialog.
  2. Select or enter the path to an existing Inklings workspace folder (one that already contains inklings.db).
  3. Observe the dialog state.

Expected: The dialog displays an error such as “Source folder is already an Inklings workspace. Open it instead of importing.” The preview step is not shown.

13. Execute import — empty folder shows zero imported in the completion summary

Import a folder that exists on the filesystem but contains no markdown files. The import should complete without error but report zero pages imported.

Steps:

  1. Open the Import dialog.
  2. Select an empty temporary directory.
  3. Review the preview (file count shows 0).
  4. Confirm the import.
  5. Observe the completion summary.

Expected: The import completes without error. The completion summary shows 0 pages imported and 0 skipped. The app does not crash or display an error state.

14. Get supported import types — import dialog offers Markdown and Obsidian source options

The import dialog’s source type selector (or auto-detection) should support at least two source types: Markdown folder and Obsidian vault.

Steps:

  1. Open the Import dialog.
  2. Look for a source type selector or observe the auto-detected type options available.

Expected: The dialog indicates support for at least “Markdown Folder” and “Obsidian Vault” as import source types. Both labels are visible in the dialog.

15. Import records an event log entry for audit trail

When an import is executed, the event log records the import operation so users can see when content was imported and what changed.

Steps:

  1. Note the current state of the workspace (number of pages).
  2. Open the Import dialog and import a valid fixture folder.
  3. After the import completes, query the event log (via timeline or page events).

Expected: The event log contains at least one entry related to the import — either individual “Created” events for each imported page or a summary import event. The events have timestamps matching the import time.

bridge:partial — Event log queries are available via bridge, but the exact event structure for import operations should be confirmed from the first test run.

16. Execute import — large fixture set completes within a reasonable time and shows correct count

Import a fixture directory containing at least 50 markdown files. The app should handle the load without freezing or timing out, and the completion summary should report the correct count.

Steps:

  1. Open the Import dialog.
  2. Select the large fixture directory (50+ .md files).
  3. Confirm the import.
  4. Wait up to 60 seconds for completion.
  5. Observe the completion summary and the sidebar.

Expected: The import completes within 60 seconds. The completion summary shows at least 50 pages imported. The app remains responsive throughout. No error banner or crash dialog appears.

bridge:partial — No progress events. The test observes only the final completion state.

17. Copy mode import — creates a new workspace at a separate path, source folder is not modified

Use the Copy import mode to import a fixture folder into a new workspace directory, leaving the source folder intact.

Steps:

  1. Open the Import dialog.
  2. Select the markdown fixture folder.
  3. In the import mode selector, choose “Copy” and specify a new target path and workspace name (“Copied Workspace”).
  4. Confirm the import.
  5. After completion, verify the app opens the new workspace.
  6. Verify the source folder still exists and does not contain an inklings.db file.

Expected: The new workspace named “Copied Workspace” opens and contains the imported pages. The source directory is unmodified (no inklings.db added). The completion summary shows at least 1 page imported.

Test Data

KeyValueNotes
markdown_fixture_dir/tmp/sentinel-qa-fixtures/markdown-basicMust contain at least 3 .md files and 1 subdirectory
obsidian_fixture_dir/tmp/sentinel-qa-fixtures/obsidian-vaultMust contain .obsidian/ directory and wiki-linked pages
nested_fixture_dir/tmp/sentinel-qa-fixtures/nested-hierarchyparent/child/grandchild.md structure
large_fixture_dir/tmp/sentinel-qa-fixtures/large-import50+ .md files
temp_target_dir/tmp/sentinel-qa-workspace-copyMust not exist before the Copy mode test

Notes

  • bridge:partial applies to all import execution scenarios — no intermediate progress events are emitted. The UI jumps from the importing indicator to the completion state.
  • The app validates that the source path is not already an Inklings workspace. Any fixture directory must be clean of inklings.db before each test run.
  • Fixture directories must be created as part of test setup (a beforeAll hook in the generated .spec.ts file is the right place).
  • Obsidian wiki-link conversion is only relevant for Obsidian vault imports; Markdown folder imports do not show a wiki-link count.
  • The default hierarchy mode preserves nested directories as nested pages. A scenario for FlattenDeep mode could be added in a future revision.

Was this page helpful?