obsidian-livesync/src/apps/cli/testdeno/test_dev_deno.md

CLI Deno Test Development Notes

This document provides an overview of the Deno-based compatibility tests under src/apps/cli/testdeno/. The Deno suite is the canonical CLI E2E entry point. P2P scenarios run through the repository Compose entry point so that networking, signalling, and the runner environment are reproducible. Existing Bash tests under src/apps/cli/test/ remain as legacy implementation references, but are not exposed as supported P2P entry points.

---

Goals

• Keep the existing Bash tests as migration references while using Deno and Compose for supported execution.
• Provide direct execution from Windows PowerShell.
• Establish a TypeScript (Deno) foundation for core end-to-end and integration scenarios.

---

Directory structure

src/apps/cli/testdeno/
  deno.json
  run-ci-suite.ts
  run-compose-p2p.ts
  CONTRIBUTING_TESTS.md
  helpers/
    backgroundCli.ts
    cli.ts
    docker.ts
    env.ts
    p2p.ts
    settings.ts
    temp.ts
  test-e2e-two-vaults-couchdb.ts
  test-push-pull.ts
  test-p2p-host.ts
  test-p2p-peers-local-relay.ts
  test-p2p-sync.ts
  test-p2p-three-nodes-conflict.ts
  test-p2p-upload-download-repro.ts
  test-e2e-two-vaults-matrix.ts
  test-setup-put-cat.ts
  test-mirror.ts
  test-sync-two-local-databases.ts
  test-sync-locked-remote.ts
  test-daemon.ts
  test-decoupled-vault.ts
  test-remote-commands.ts

---

Key files

deno.json

• Defines Deno tasks.
• Defines import maps for @std/assert and @std/path.

Main tasks:

• deno task test
• deno task test:ci
• deno task test:p2p:compose
• deno task test:local
• deno task test:daemon
• deno task test:decoupled-vault
• deno task test:remote-commands
• deno task test:push-pull
• deno task test:setup-put-cat
• deno task test:mirror
• deno task test:sync-two-local
• deno task test:sync-locked-remote
• deno task test:p2p-host
• deno task test:p2p-peers
• deno task test:p2p-sync
• deno task test:p2p-three-nodes
• deno task test:p2p-upload-download
• deno task test:e2e-couchdb
• deno task test:e2e-matrix

deno task test is an alias for the non-P2P test:ci suite. The individual P2P tasks are explicit host-direct entry points for cross-platform diagnostics; they are never selected by the default suite or CI. Use test:p2p:compose for canonical P2P verification.

helpers/cli.ts

• CLI execution wrappers.
• runCli, runCliOrFail, runCliWithInput.
• Output normalisation via sanitiseCatStdout.
• Comparison utilities, including assertFilesEqual.

This file corresponds to run_cli and common assertions in test-helpers.sh.

helpers/settings.ts

• Executes init-settings --force.
• Marks isConfigured = true.
• Applies CouchDB and P2P settings.
• Applies remote synchronisation settings and P2P test tweaks.

This file corresponds to settings helpers in test-helpers.sh.

helpers/docker.ts

• Starts, stops, and initialises CouchDB directly from Deno.
• Configures CouchDB via fetch + retry.
• Starts and stops the P2P relay through the same Docker runner.

Both CouchDB and P2P relay flows are bash-independent.

helpers/backgroundCli.ts

• Starts long-running commands such as p2p-host in the background.
• Waits for readiness logs and handles termination.

helpers/p2p.ts

• Determines whether a local relay should be started.
• Parses p2p-peers output.
• Discovers peer IDs with a fallback based on advertisement logs.

helpers/env.ts

• Loads .test.env.
• Supports KEY=value, single-quoted values, and double-quoted values.

helpers/temp.ts

• Provides TempDir.
• Uses await using to auto-clean temporary directories.

---

Implemented tests

test-push-pull.ts

• Verifies push and pull round trips.
• Uses environment variables or .test.env for CouchDB values.

test-setup-put-cat.ts

• Verifies setup with full setup URI generation via encodeSettingsToSetupURI.
• Verifies push, cat, ls, info, rm, resolve, cat-rev, and pull-rev.
• Does not require an external remote.

test-mirror.ts

• Verifies six core mirror scenarios.
• Does not require an external remote.

test-sync-two-local-databases.ts

• Verifies sync between two vaults and CouchDB.
• Verifies conflict detection and resolve propagation.
• Starts Docker CouchDB by default when LIVESYNC_START_DOCKER != 0.

test-sync-locked-remote.ts

• Updates the CouchDB milestone locked flag.
• Verifies sync success when unlocked.
• Verifies actionable CLI error when locked.

test-p2p-host.ts

• Verifies that p2p-host starts and emits readiness output.

test-p2p-peers-local-relay.ts

• Verifies peer discovery through a local relay.

test-p2p-sync.ts

• Verifies that p2p-sync completes after peer discovery.

test-p2p-three-nodes-conflict.ts

• Uses one host and two clients.
• Verifies conflict creation, detection via info, and resolution via resolve.

test-p2p-upload-download-repro.ts

• Uses host, upload, and download nodes.
• Verifies transfer of text files and binary files, including larger files.

test-e2e-two-vaults-couchdb.ts

• Verifies two-vault end-to-end scenarios on CouchDB.
• Runs both encryption-off and encryption-on cases.
• Includes conflict marker checks in ls and resolve propagation checks.

test-e2e-two-vaults-matrix.ts

• Verifies the matrix equivalent of the bash script.
• Runs four combinations:
  • COUCHDB-enc0
  • COUCHDB-enc1
  • MINIO-enc0
  • MINIO-enc1

test-daemon.ts

• Verifies daemon-related ignore rules behaviour.
• Exercises scenarios with .livesync/ignore wildcard rules, missing ignore rules, and imported .gitignore rules.

test-decoupled-vault.ts

• Verifies push, pull, and mirror command behaviour when the vault directory is decoupled from the database directory.

test-remote-commands.ts

• Verifies remote database management commands: remote-status, lock-remote, unlock-remote, and mark-resolved.

---

Running tests (PowerShell)

From the repository root, use the canonical package scripts. test:e2e:cli runs the same non-P2P task set selected by the default CLI CI workflow. P2P validation runs in Compose so peer discovery does not depend on host loopback, firewall, or WebRTC candidate behaviour.

npm run test:e2e:cli
npm run test:e2e:cli:p2p
npm run test:e2e:cli:all

From src/apps/cli/testdeno:

cd src/apps/cli/testdeno

# Canonical suites
deno task test:ci
deno task test:p2p:compose

# Local-only set
deno task test:local

# Individual tests
deno task test:setup-put-cat
deno task test:mirror
deno task test:daemon
deno task test:push-pull
deno task test:sync-locked-remote

# CouchDB-based tests
deno task test:sync-two-local
deno task test:decoupled-vault
deno task test:remote-commands
deno task test:e2e-couchdb

# Explicit host-direct P2P diagnostics for cross-platform investigations.
# These are not part of the default suite or release evidence.
deno task test:p2p-host
deno task test:p2p-peers
deno task test:p2p-sync
deno task test:p2p-three-nodes
deno task test:p2p-upload-download
deno task test:e2e-matrix

---

Environment variables

CouchDB

• COUCHDB_URI
• COUCHDB_USER
• COUCHDB_PASSWORD
• COUCHDB_DBNAME

Equivalent keys in src/apps/cli/.test.env:

• hostname
• username
• password
• dbname

Behaviour switches

• LIVESYNC_START_DOCKER=0: use existing CouchDB.
• REMOTE_PATH: override target path for selected tests.
• LIVESYNC_TEST_TEE=1: stream CLI stdout and stderr during execution.
• LIVESYNC_DOCKER_TEE=1: stream Docker stdout and stderr.
• LIVESYNC_CLI_RETRY=<n>: retry transient network failures.
• LIVESYNC_DEBUG_KEEP_DOCKER=1: keep couchdb-test after test completion.

Docker command selection

helpers/docker.ts supports command selection via environment variables.

• LIVESYNC_DOCKER_MODE=auto (default)
  • Windows: tries wsl docker first, then docker.
  • Non-Windows: tries docker first, then wsl docker.
• LIVESYNC_DOCKER_MODE=native: always uses docker.
• LIVESYNC_DOCKER_MODE=wsl: always uses wsl docker.
• LIVESYNC_DOCKER_COMMAND="...": custom command, for example wsl docker.

LIVESYNC_DOCKER_COMMAND has priority over LIVESYNC_DOCKER_MODE.

PowerShell examples:

# Use Docker in WSL explicitly
$env:LIVESYNC_DOCKER_MODE = "wsl"
deno task test:sync-two-local

# Full custom command
$env:LIVESYNC_DOCKER_COMMAND = "wsl docker"
deno task test:sync-two-local

P2P

• RELAY
• ROOM_ID
• PASSPHRASE
• APP_ID
• PEERS_TIMEOUT
• SYNC_TIMEOUT
• USE_INTERNAL_RELAY=0|1
• TIMEOUT_SECONDS

---

Continuous Integration

The GitHub Actions workflow .github/workflows/cli-deno-tests.yml runs automatically on pushes and pull requests affecting the CLI, executing the non-P2P test suite (test:ci). P2P tests (test:p2p) are excluded from automatic execution and must be run via manual dispatch (workflow_dispatch). You can optionally check the "Enable verbose and debug logging" checkbox during a manual dispatch to produce detailed trace logs for troubleshooting.

---

Current limitations

• MinIO startup and matrix coverage are ported. Current limits are elsewhere, not setup URI generation.

---

Maintenance policy

• Existing bash tests remain available.
• Deno tests are expanded in parallel for cross-platform usage.
• New scenarios should be added through reusable helpers in helpers/.