Skip to content
Codex
Documentation GitHub
Workspace

Workspace Operations

Workspace Operations

Covers the full lifecycle of a workspace: initialization, renaming, setting an icon, opening an existing workspace, switching between workspaces, and managing the recent-workspaces list. These are the first actions a new user takes and must be reliable before any page work begins.

Preconditions

  • HTTP bridge running on port 9990
  • Bridge shim injected via playwright.config.ts
  • No pre-existing workspace at the test path (bridge starts fresh via --workspace flag)

Scenarios

Seed: seed.spec.ts

1. Initialize a workspace with explicit name and path

Create a new workspace by completing the onboarding flow with both a name and a path.

Steps:

  1. Launch the app. The onboarding screen appears asking for a workspace name.
  2. Type “My Novel” into the workspace name field.
  3. Confirm the default path or choose a path, then click the button to create the workspace.

Expected: The app transitions out of the onboarding screen. The sidebar displays “My Novel” as the active workspace name. The main editor area is visible and ready for use.

2. Initialize a workspace with path only (name derived from folder)

When the user picks a folder but leaves the name field empty or defaulted, the workspace name is derived from the folder’s base name.

Steps:

  1. Launch the app to the onboarding screen.
  2. Leave the workspace name field at its default (not manually typed).
  3. Select or type a folder path whose base name is “fantasy-world”.
  4. Confirm to create the workspace.

Expected: The sidebar displays “fantasy-world” as the workspace name (derived from the folder). The workspace is active and usable.

3. Initialize workspace with no arguments returns pre-initialized workspace

If the app launches and a workspace is already initialized, it should re-open the existing workspace rather than starting the onboarding flow again.

Steps:

  1. Complete onboarding and create a workspace.
  2. Note the workspace name shown in the sidebar.
  3. Close the app and relaunch it.

Expected: The app opens directly into the previously created workspace without showing the onboarding screen. The workspace name in the sidebar matches the name from the first launch. No duplicate workspace is created.

4. Get current workspace after initialization

After initialization, the workspace name is visible in the sidebar header.

Steps:

  1. Complete the onboarding flow and create a workspace named “Test Vault”.

Expected: The sidebar header displays “Test Vault”. The main editor area is accessible, confirming the workspace is active.

5. Rename a workspace

The workspace name can be changed from the workspace settings.

Steps:

  1. Create a workspace named “Old Name”.
  2. Open workspace settings (e.g., click the workspace name in the sidebar or access the settings panel).
  3. Find the workspace name field and change it from “Old Name” to “New Name”.
  4. Save or confirm the rename.

Expected: The sidebar immediately updates to show “New Name” as the workspace title. After the change is saved, the new name persists (observable in the sidebar header).

6. Rename workspace — empty name is rejected

An empty string must be rejected when attempting to rename a workspace.

Steps:

  1. Create a workspace and open its settings.
  2. Clear the workspace name field so it is empty.
  3. Attempt to save or confirm the rename.

Expected: The rename is not accepted. An error message or validation indicator appears near the name field (e.g., “Name cannot be empty”). The workspace name in the sidebar remains unchanged.

7. Rename workspace — name with forbidden characters is rejected

Workspace names must be filesystem-safe. Characters like /, \, :, *, ?, ", <, >, | are forbidden.

Steps:

  1. Create a workspace and open its settings.
  2. Change the workspace name to “My:Workspace” (a colon is a forbidden character).
  3. Attempt to save or confirm the rename.

Expected: The rename is rejected. An error or validation message appears indicating the name contains an invalid character. The workspace name is unchanged.

8. Rename workspace — name exceeding 100 characters is rejected

The domain enforces a maximum workspace name length of 100 characters.

Steps:

  1. Create a workspace and open its settings.
  2. Paste a name that is 101 characters long into the workspace name field.
  3. Attempt to save or confirm the rename.

Expected: The rename is rejected. An error message appears indicating the name is too long. The workspace name is unchanged.

9. Rename workspace — reserved Windows name is rejected

Names like CON, NUL, PRN, COM1–COM9, LPT1–LPT9 are rejected for Windows cross-platform compatibility (case-insensitive).

Steps:

  1. Create a workspace and open its settings.
  2. Change the workspace name to “CON”.
  3. Attempt to save.
  4. Change the workspace name to “nul” (lowercase).
  5. Attempt to save again.

Expected: Both attempts are rejected with a validation error. The workspace name remains unchanged after both attempts.

10. Set a workspace icon

A workspace can have an icon displayed next to its name in the sidebar.

Steps:

  1. Create a workspace.
  2. Open workspace settings.
  3. Observe whether an icon picker is available.

Expected: The initial workspace displays no custom icon next to its name in the sidebar. If an icon picker is available in settings, this scenario documents the current state of that capability. Note: icon setting may only be available through the desktop app’s workspace settings UI, not through the onboarding flow.

11. Open an existing workspace by path

A previously created workspace can be reopened from the recent workspaces list or by browsing to its folder.

Steps:

  1. Create a workspace (which adds it to the recent workspaces list).
  2. Use the workspace switcher or “Open Workspace” option to browse to that workspace’s folder.
  3. Confirm the open action.

Expected: The app loads the selected workspace. The sidebar displays the correct workspace name for the reopened workspace. The page tree reflects the workspace’s contents.

12. Open non-existent workspace returns NotFound error

Attempting to open a folder that has no workspace database should produce a clear error.

Steps:

  1. Use the “Open Workspace” or folder-browse option.
  2. Navigate to a folder that contains no workspace data (e.g., an empty folder or a non-existent path).
  3. Confirm the open action.

Expected: An error message or toast appears indicating the selected folder is not a valid workspace (e.g., “No workspace found at this location”). The app does not crash and remains on the current screen.

13. Check folder status — empty folder

Before workspace creation, the UI checks folder status to inform the user.

Steps:

  1. Start the onboarding flow or open the workspace folder picker.
  2. Select an empty folder (one that exists on disk but contains no workspace data).

Expected: The UI indicates the folder is available for a new workspace (e.g., no warning about existing data, folder is shown as suitable for creation).

14. Check folder status — already a workspace

A folder that already contains a workspace database reports its workspace name.

Steps:

  1. Create a workspace at a specific path.
  2. Start the onboarding flow or folder picker again.
  3. Select that same folder.

Expected: The UI indicates this folder already contains a workspace and shows the existing workspace name (e.g., “This folder already contains the workspace ‘my-workspace’”). The user is prompted to open it rather than create a new one.

15. Check folder status — non-existent path reports Empty

A path that does not yet exist on disk should be treated as available for creation.

Steps:

  1. Start the onboarding flow or folder picker.
  2. Type in a path to a folder that does not exist yet.

Expected: The UI treats the path as available (empty/new) and allows the user to proceed with workspace creation at that path.

16. Get workspaces directory

The app stores workspaces in a known directory that the user can access.

Steps:

  1. Open the app settings or workspace management panel.
  2. Look for a “Workspaces folder” or storage location display.

Expected: A path to the workspaces directory is visible in the UI. In the dev environment this points to .data/workspaces/. The path is non-empty and absolute.

17. Get default workspace path

The app has a canonical default workspace location.

Steps:

  1. Open the onboarding flow or workspace creation dialog.
  2. Observe the pre-filled or default path shown in the folder path field.

Expected: The default path is pre-populated and ends with /Default (or the platform-appropriate equivalent). The user can accept this default or change it.

18. Get storage directory

The app exposes its storage root directory in settings.

Steps:

  1. Open the app settings or about panel.
  2. Look for a storage directory or data path display.

Expected: The storage root path is shown as a non-empty absolute path. The user can see where app data is stored.

19. Switch between two workspaces

A user can switch from one open workspace to another, making the second one active.

Steps:

  1. Create workspace A (it becomes the active workspace; its name is in the sidebar).
  2. Use the workspace switcher to open workspace B (create it or open an existing one).
  3. Observe the sidebar after opening workspace B.
  4. Use the workspace switcher again to switch back to workspace A.
  5. Observe the sidebar.

Expected: After opening workspace B, the sidebar header changes to show workspace B’s name and its page tree. After switching back to workspace A, the sidebar header shows workspace A’s name. Both workspaces remain intact — switching does not delete either one.

20. Workspace name with Unicode characters

Workspace names can contain Unicode characters that are valid on the filesystem.

Steps:

  1. Complete the onboarding flow.
  2. Type “Mein Projekt — Frühjahr” as the workspace name.
  3. Create the workspace.

Expected: The sidebar displays “Mein Projekt — Frühjahr” with correct Unicode characters. The name is not corrupted, truncated, or mangled in the display.

21. Workspace name with leading/trailing dots is rejected

Domain rule: workspace names cannot start or end with a dot.

Steps:

  1. Open the onboarding flow or workspace rename field.
  2. Type “.hidden-workspace” as the workspace name.
  3. Attempt to create or save.

Expected: The name is rejected with a validation error (e.g., “Name cannot start with a dot”). No workspace is created.

22. Get workspace database path

The app can reveal the path to a workspace’s database file.

Steps:

  1. Create a workspace.
  2. Open workspace settings or an “about this workspace” panel that shows storage details.

Expected: The database file path is shown and ends with inklings.db. This confirms the workspace’s storage location.

23. Add a workspace to the recent list

When a workspace is opened, it appears in the recent workspaces list.

Steps:

  1. Open a workspace (via onboarding or the workspace switcher).
  2. Open the workspace switcher or recent workspaces menu.

Expected: The workspace appears in the recent workspaces list with its correct name and path. The list is accessible from the workspace switcher.

24. Opening a workspace auto-adds it to the recent list

Each time a workspace is opened, it is recorded in the recent workspaces list.

Steps:

  1. Create and open a workspace named “Auto Recent”.
  2. Open the recent workspaces menu.

Expected: “Auto Recent” appears in the recent workspaces list. No duplicate entries exist for the same workspace.

25. Recent list is sorted with most recently accessed first

When multiple workspaces are in the recent list, the most recently accessed one appears at the top.

Steps:

  1. Open workspace “Older WS” and then switch away from it.
  2. Open workspace “Newer WS”.
  3. Open the recent workspaces menu.

Expected: “Newer WS” appears above “Older WS” in the recent list. The list is ordered by most recently accessed first.

26. Adding the same workspace twice updates its timestamp rather than duplicating it

Re-opening an existing workspace should move it to the top of the recent list without creating a duplicate.

Steps:

  1. Open workspace “Dedup WS” (first time — it appears in the recent list).
  2. Switch away and then re-open “Dedup WS”.
  3. Open the recent workspaces menu.

Expected: “Dedup WS” appears exactly once in the recent list, at the top (most recent). No duplicate entries with the same workspace name or path.

27. Remove a workspace from the recent list

A specific workspace can be removed from the recent list without affecting others.

Steps:

  1. Ensure two workspaces are in the recent list: “Keep Me” and “Remove Me”.
  2. Open the recent workspaces menu.
  3. Find “Remove Me” and use its remove/dismiss action (e.g., an X button or right-click → Remove from recents).

Expected: “Remove Me” disappears from the recent list. “Keep Me” remains in the list. No error occurs.

28. Remove a workspace not in the recent list is a no-op

Dismissing a workspace that is no longer in the list must not error.

Steps:

  1. Open the recent workspaces menu.
  2. Attempt to remove a workspace entry that is not present (e.g., one that was already removed).

Expected: No error occurs. The existing recent list is unmodified.

29. Clear all recent workspaces

All entries in the recent workspaces list can be cleared at once.

Steps:

  1. Ensure at least three workspaces are in the recent list.
  2. Find and use a “Clear all recent workspaces” or “Clear history” action in the workspace switcher or settings.

Expected: All entries are removed from the recent workspaces list. The list is now empty (shows “No recent workspaces” or similar empty state). No error occurs.

30. Clear recent workspaces when list is already empty is a no-op

Clearing an already-empty recent list must not error.

Steps:

  1. Clear the recent workspaces list (or start with an empty list).
  2. Attempt to clear it again.

Expected: No error occurs. The recent list remains empty.

31. Recent list persists across conceptual “sessions” (settings persistence)

The recent workspaces list is stored persistently so it survives app restarts.

Steps:

  1. Open a workspace named “Persistent WS” so it appears in the recent list.
  2. Close and relaunch the app.
  3. Open the recent workspaces menu.

Expected: “Persistent WS” still appears in the recent workspaces list after the relaunch. The list is persisted to disk (the JSON settings file) and survives across sessions.

32. Refresh recent workspaces menu returns 501 from bridge

The native OS menu refresh is not available in the browser-based test environment.

Steps:

  1. Observe that the recent workspaces list is displayed in the UI (populated via the normal open/switch flows).

Expected: The recent workspaces list is populated correctly from the in-app UI. Any native OS menu bar item for recent workspaces is not testable in this environment — this is a known limitation of the bridge and must not be treated as a test failure.

Test Data

KeyValueNotes
valid_nameMy NovelStandard workspace name
unicode_nameMein Projekt — FrühjahrMulti-byte Unicode workspace name
too_long_name”a” * 101 charactersExactly 1 character over the 100-char limit
forbidden_char_nameMy:WorkspaceColon is forbidden
reserved_nameCONWindows reserved device name
reserved_name_lowercasenulReserved names are case-insensitive
leading_dot_name.hidden-workspaceLeading dot is forbidden
nonexistent_path/tmp/does-not-exist-inklings-qaPath that has never been created
recent_ws_name_1Older WSFirst entry for ordering test
recent_ws_name_2Newer WSSecond entry — should sort above Older WS
dedup_ws_nameDedup WSRe-added to verify no duplicate entries
remove_ws_nameRemove MeTarget for remove_from_recent_workspaces test
keep_ws_nameKeep MeMust survive the remove_from_recent_workspaces call
persistent_ws_namePersistent WSVerifies settings-file persistence

Notes

  • The bridge holds a single “current workspace” in memory. Switching workspaces does NOT reload the page repository — tests that switch workspaces and then operate on pages may observe stale state. Re-test page operations after switching workspaces.
  • rename_workspace performs a directory rename on disk. In the bridge environment (.data/workspaces/), this is an in-place filesystem operation; verify the path field in the response reflects the new folder name.
  • refresh_recent_workspaces_menu always returns HTTP 501 from the bridge — this is expected and documented in recent_workspaces.rs. Do not treat this as a test failure (scenario 32).
  • Icon setting for workspaces does not have a dedicated bridge route; workspace icons are managed through the desktop Tauri app’s settings panel.
  • add_to_recent_workspaces canonicalizes the path via std::path::Path::canonicalize. For paths to directories that do not yet exist on disk, canonicalization falls back to the raw path. When asserting path equality, use the same form that was provided (or the canonical form if the directory exists).
  • The recent-workspaces list is stored in the JSON settings file at .data/settings.json (dev environment). Its contents are separate from the in-memory workspace state managed by current_workspace.

Was this page helpful?