jerry/buzz

mirror of https://github.com/block/buzz.git synced 2026-11-02 23:41:08 +00:00

Files

npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl 23f75dac90 docs: write full documentation content (Phase 2)

Fill all 31 stub pages scaffolded in Phase 1 with content migrated and
verified from the root docs, crate READMEs, and source code:

- getting-started/ (3): installation, quickstart, local relay (TESTING.md)
- architecture/ (8): ARCHITECTURE.md §1–§8, one page per section
- guides/ (9): development, testing, agents, workflows, self-hosting,
  nostr-clients (operational half of NOSTR.md), adding-event-kinds,
  adding-api-endpoints, releasing
- reference/ (5): CLI reference verified against buzz --help and
  crates/buzz-cli/src (18 groups / 87 subcommands; README drift noted),
  configuration, known-limitations (ARCHITECTURE §9 + conformance
  LIMITS.md + doc-debt list), NIPs index (13, NIP-CW canonical),
  design-docs index
- vision/ (6): VISION.md + 5 VISION_*.md migrated with aspirational
  banners and rewritten links

Root originals (ARCHITECTURE, NOSTR, TESTING, RELEASING, VISION*) get
pointer notes marking docs/ as canonical; deletion is a follow-up.
All relative links in the new tree verified to resolve.

Known limitations are documented honestly, never papered over:
rate limiting unenforced, WF-07/WF-08 workflow stubs, buzz-cli README
drift, one-line GOVERNANCE.md.

Note: pre-commit sadscan findings reviewed as false positives (dev-default
postgres URI and NIP-OA test vectors, both already on origin/main).

Co-authored-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>
Signed-off-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>

2026-07-07 12:14:33 -07:00

2.9 KiB

Raw Blame History

Testing Guide

How to run and write tests. For the full CLI-driven live-relay walkthrough (build, smoke test, ACP harness), see Running a Local Relay.

Automated tests

just test-unit          # unit tests — no infrastructure needed
just test               # unit + integration (starts Docker if needed)

just test runs unit tests plus integration tests against Postgres and Redis (started automatically if not already running). Neither task runs the E2E suites in buzz-test-client — those are marked #[ignore] and require a running relay:

# Start a relay first (see below), then:
cargo test -p buzz-test-client -- --ignored

Unit Tests (no infrastructure required)

just test-unit

Unit tests are self-contained and run without Docker. They cover event parsing, filter matching, auth logic, workflow YAML parsing, and more.

Integration Tests (requires running infrastructure)

just test

Integration tests spin up the relay and exercise the full stack — WebSocket connections, NIP-42 auth, event ingestion, search indexing, and workflow execution. just test starts Docker services automatically if they're not already running.

End-to-End Tests

End-to-end tests live in crates/buzz-test-client/tests/:

e2e_relay.rs — WebSocket relay tests
e2e_mcp.rs — MCP tool tests
e2e_nostr_interop.rs — Nostr protocol interoperability tests
e2e_media.rs — media upload/download tests
e2e_media_extended.rs — extended media tests (GIF, image processing)

Run them with (requires running infrastructure):

cargo test -p buzz-test-client -- --ignored

See TESTING.md for the full multi-agent E2E testing guide.

CI Gate

Before opening a PR, run the full CI gate locally:

just ci
# Runs: check + unit tests + desktop build + Tauri check + mobile tests

This is the same check that runs in CI. PRs that fail just ci will not be merged.

Desktop tests

The desktop app has Playwright end-to-end tests configured in desktop/playwright.config.ts (plus a perf config, playwright.perf.config.ts). Run them from desktop/ with pnpm.

Conformance

crates/buzz-conformance is a runtime conformance gate that checks relay ingest/auth/read decisions against the formal specs in docs/spec/. It validates traces from executions that actually ran — it is not a proof; read crates/buzz-conformance/LIMITS.md before treating a green run as more than execution coverage.

CLI smoke-testing against a live relay

See Running a Local Relay for the end-to-end sequence (keypair → channel → message → thread), and crates/buzz-cli/TESTING.md for full coverage of every CLI command.

2.9 KiB Raw Blame History