From 11bcbefb6978bcc02858fbcef60c14bf2ec4514c Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Thu, 18 Dec 2025 17:23:31 +0000 Subject: docs: document sync test refactoring findings and patterns - Add comprehensive test pattern guidance to tests/sync/mod.rs - Explain when to use run_sync_test() vs manual setup - Document helper scope and architectural limitations Key findings: - historic_sync.rs: 4 tests refactored, 143 lines removed (50% reduction) - live_sync/discovery/tag_variations: Manual setup required due to architectural incompatibilities (timing, multi-relay, assertions) - Helper works for batch historic verification, not real-time scenarios Detailed summary available in work/sync-test-refactor-summary.md --- tests/sync/mod.rs | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 108 insertions(+), 6 deletions(-) (limited to 'tests/sync') diff --git a/tests/sync/mod.rs b/tests/sync/mod.rs index ffda73e..58b7354 100644 --- a/tests/sync/mod.rs +++ b/tests/sync/mod.rs @@ -3,7 +3,7 @@ //! This module organizes tests for ngit-grasp's proactive sync functionality. //! Tests are grouped by sync scenario: //! -//! - Bootstrap sync (relay syncs from pre-configured bootstrap relay) +//! - Historic sync (relay syncs from pre-configured bootstrap relay) //! - Relay discovery (relay discovers other relays from announcement events) //! - Live sync (events sync in real-time after connection established) //! - Tag variations (testing different Layer 2/3 tag types: a/A/q, e/E/q) @@ -12,17 +12,119 @@ //! //! # Test Files //! -//! - `bootstrap.rs` - Tests 1, 4: sync from bootstrap relay -//! - `discovery.rs` - Tests 2, 3: relay discovery from announcements -//! - `live_sync.rs` - Tests 5, 6, 7: real-time sync after connection -//! - `tag_variations.rs` - Tests 8, 9: Layer 2/3 tag type coverage -//! - `catchup.rs` - Test 0: catchup after disconnect (stub, `#[ignore]`) +//! - `historic_sync.rs` - Bootstrap and replay tests (uses `run_sync_test()` helper) +//! - `discovery.rs` - Relay discovery from announcements (manual setup required) +//! - `live_sync.rs` - Real-time sync after connection (manual setup required) +//! - `tag_variations.rs` - Layer 2/3 tag type coverage (manual setup required) +//! - `catchup.rs` - Catchup after disconnect (stub, `#[ignore]`) //! - `metrics.rs` - Prometheus metrics integration tests //! +//! # Test Patterns +//! +//! This module uses two main testing approaches, each suited to different scenarios: +//! +//! ## Pattern 1: Helper-Based Tests (Historic Sync) +//! +//! **Use `run_sync_test()` for:** +//! - Verifying historic event sync (events published before relay starts) +//! - Bootstrap and initialization tests +//! - Simple count-based event verification +//! - Single-relay scenarios +//! +//! **Example from `historic_sync.rs`:** +//! ```rust +//! use common::sync_helpers::{run_sync_test, build_layer2_issue_event}; +//! +//! #[tokio::test] +//! async fn test_bootstrap_syncs_existing_layer2_events() { +//! let repo_event = /* create repo announcement */; +//! let issue1 = build_layer2_issue_event(&repo_event, "Issue 1"); +//! let issue2 = build_layer2_issue_event(&repo_event, "Issue 2"); +//! +//! run_sync_test( +//! &[&repo_event], // Bootstrap events +//! &[&issue1, &issue2], // Events to verify +//! 2, // Expected count +//! ).await; +//! } +//! ``` +//! +//! **Helper Architecture:** +//! - Publishes all events to bootstrap relay before target relay starts +//! - Automatically starts target relay with bootstrap relay configured +//! - Verifies event counts after sync completes +//! - Handles all relay lifecycle management +//! +//! ## Pattern 2: Manual Setup Tests (Live, Discovery, Tag Variations) +//! +//! **Use manual setup for:** +//! - Live sync (events published *during* relay operation) +//! - Multi-relay coordination (discovery chains) +//! - Detailed event inspection (tag format verification) +//! - Precise timing control +//! +//! **Example from `live_sync.rs`:** +//! ```rust +//! #[tokio::test] +//! async fn test_live_sync_layer2_events() { +//! let bootstrap = TestRelay::start().await; +//! let target = TestRelay::start_with_bootstrap(bootstrap.url()).await; +//! +//! // Publish AFTER relay is running (live sync) +//! let event = build_layer2_issue_event(&repo, "Live Issue"); +//! client.publish_event(event).await; +//! +//! // Verify with timing control +//! wait_for_event_on_relay(&target, &event.id, timeout).await; +//! } +//! ``` +//! +//! **Example from `discovery.rs`:** +//! ```rust +//! #[tokio::test] +//! async fn test_recursive_relay_discovery() { +//! // Multi-relay orchestration +//! let relay1 = TestRelay::start().await; +//! let relay2 = TestRelay::start().await; +//! let relay3 = TestRelay::start().await; +//! +//! // relay1 announces relay2, relay2 announces relay3 +//! // Verify relay1 discovers relay3 through chain +//! } +//! ``` +//! +//! **Example from `tag_variations.rs`:** +//! ```rust +//! #[tokio::test] +//! async fn test_layer2_sync_with_uppercase_a_tag() { +//! // Detailed tag format verification +//! let event = build_event_with_uppercase_A(); +//! +//! // Custom assertions about tag normalization +//! assert!(synced_event.tags.contains_uppercase_a()); +//! } +//! ``` +//! +//! ## Why Two Patterns? +//! +//! The `run_sync_test()` helper embodies a specific pattern: +//! ``` +//! Setup → Publish Batch → Start Relay → Verify Counts +//! ``` +//! +//! This pattern is **incompatible** with tests needing: +//! - Event publication *during* relay operation (live sync) +//! - Multiple relay coordination (discovery) +//! - Detailed event inspection beyond counts (tag variations) +//! - Precise timing control +//! +//! For these scenarios, manual setup provides necessary flexibility. +//! //! # Shared Imports //! //! All sync tests use helpers from `common::sync_helpers`: //! - `TestClient` - Client with retry logic +//! - `run_sync_test()` - Helper for historic sync tests //! - Event builders for Layer 2/3 events //! - `wait_for_event_on_relay()` - Non-panicking assertion helper //! - `fetch_metrics()` - Prometheus metrics fetching -- cgit v1.2.3