Testing and troubleshooting

Start with the failing entry, exact app root, installed package artifacts and runtime. Record the reproducible command and expected behavior. Inspect only necessary environment-key presence; do not dump configuration or secrets to diagnose a missing setting.

These workflows refer to the audited TypeScript source at 549b987. Source checkout commands must be matched to an external app's real installed package exports and scripts.

Keep the feedback loop narrow

In the framework checkout, package exports resolve to dist. Build changed framework packages and dependencies before consumer tests/typechecks. Do not typecheck a consumer while another build clears that output. In an external application, use its installed artifacts and existing scripts; no framework checkout is required.

From the reviewed checkout root:

1bun run cli help --json2bun run cli inspect notes-operations create --root examples/notes --json3bun run --filter @lenso/example-notes typecheck4bun test examples/notes/test/operations.test.ts

The operation test uses isolated temporary SQLite/files and test-only identities. A read command still starts every installed plugin and may acquire resources. Only call a business operation after understanding the whole app's setup, trusted identity and target:

1# Database, migration and a verified NOTES_SESSION are already configured.2printf '%s\n' '{}' |3  bun run cli call notes-operations list --root examples/notes --stdin --json

inspect imports trusted canonical config and converters but starts neither app nor Engine setup. It describes declarations, not database health or resolved config. check/generate/build run trusted Engine setup; generation/build write owned output. dev also runs the app. Those are different diagnostic effects.

Test ordinary services and ownership

Shared service tests should cover valid/invalid business input and the actual owner/tenant policy. An HTTP middleware test alone cannot establish that CLI/MCP/direct calls enforce the same rules. Keep fixed tokens and actors confined to fixtures; a production Auth source must verify real evidence.

Test resource failure paths as well as successful startup. This Bun unit test checks cleanup registered by a setup that later fails:

1import { expect, test } from "bun:test";2import { definePlugin, startApp } from "@lenso/core";3
4test("failing setup releases its acquired resource", async () => {5  let released = false;6  const resource = definePlugin({7    id: "resource",8    setup(context) {9      context.onCleanup(() => { released = true; });10      throw new Error("test setup failure");11    },12  });13  await expect(startApp({ plugins: [resource] })).rejects.toThrow("test setup failure");14  expect(released).toBe(true);15});

The lifecycle tests additionally cover global LIFO, disposer sharing, repeated stop and aggregated failures. For a real resource, verify that owned clients close and borrowed clients survive. Streaming entries must test body completion/cancellation, not just response creation.

Use real integration evidence where it matters

Database/platform checks need their explicit prerequisites:

1# Dedicated disposable DB; environment already contains its URL.2LENSO_TEST_DATABASE_URL="$DATABASE_URL" bun test examples/notes/test/postgres.test.ts3TASK_TEST_DATABASE_URL="$DATABASE_URL" bun test packages/tasks/test/postgres.test.ts4
5# Existing local workerd/D1 setup, from the source root.6bun run --cwd examples/workers test:notes

The Notes PostgreSQL test exercises real CLI/HTTP. The Tasks provider test creates uniquely named queues and exercises real processes/SIGKILL. The Tasks example integration test is separate: run its explicit migration on an isolated DB first, then TASK_TEST_DATABASE_URL="$DATABASE_URL" bun test src/postgres.test.ts src/entry.test.ts from examples/tasks. Those example tests do not migrate or delete shared data.

Auth's LENSO_REQUIRE_POSTGRES=1 bun test packages/auth/test/postgres.test.ts requires installed PostgreSQL binaries and starts private loopback clusters; the required flag fails instead of skipping if unavailable. Local workerd tests establish local D1 behavior, not production replication. Report missing prerequisites and skipped tests as gaps, never as passing persistence/deployment checks.

Read code, phase and ordered causes

Finite CLI commands put one schemaVersion: 1 JSON envelope on stdout and logs on stderr. Exit 2 identifies arguments/input, 3 identifies discovery/assembly, and 1 identifies runtime/build/output failure. dev --json is unsupported. Use the diagnostic's actual code, phase, source and ordered causes before deciding on a fix.

For example, Notes rejects a blank title before setup:

1printf '%s\n' '{"title":" "}' |2  bun run cli call notes-operations create --root examples/notes --stdin --json

Expected evidence is code: "invalid-input", phase: "input", exit 2 and a safe field path for title; no DB or session should be needed to reject it. The existing operation tests verify that validation happens before setup.

Configuration preflight may read sources but begins before business setup. Static inspect never invokes source.read. A missing file/source, invalid env conversion and trusted TS config import are different failures; see configuration.

Avoid replay after uncertainty

Cleanup is resource release, not compensation. An output error, cleanup error, lost response or telemetry timeout can follow a committed business write. Query the application's authorized state before retrying. Task cancellation and final status do not prove all external effects were rolled back; use task recovery rules.

Check generated-output failures at the source/owner boundary. .lenso and dist are reproducible output: edit source/config and regenerate, rather than patching generated files or deleting unrelated work. Missing/mismatched database schema calls for an explicit authorized migration workflow, not a startup workaround.

Finish with a useful report

Report the runtime/package baseline, reproduced command, diagnostic code/phase/source, focused changes and checks actually run. Separate local fixtures, real DB/workerd evidence and skips. Mention unresolved state after uncertain side effects and name a missing authorized status/log interface when it prevents diagnosis. Use observability for existing stderr/backend evidence and Manage for explicitly selected authorized operations. There is no generic Observe query command or automatic remote control service.