From c2c0cdba4af434043f3fa707231d8f5a7e3fd882 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Tue, 4 Nov 2025 14:33:18 +0000
Subject: add announcement tests

---
 README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 58 insertions(+), 12 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 920d1d5..0d454bc 100644
--- a/README.md
+++ b/README.md
@@ -76,17 +76,22 @@ This approach provides:
 git clone https://gitworkshop.dev/ngit-grasp
 cd ngit-grasp
 
-# Build
-cargo build --release
+# Build (using Nix for reproducible environment)
+nix develop -c cargo build --release
 
 # Configure
 cp .env.example .env
 # Edit .env with your settings
 
 # Run
-cargo run --release
+nix develop -c cargo run --release
+
+# Run tests
+nix develop -c cargo test --lib
 ```
 
+**Don't have Nix?** See [Getting Started Tutorial](docs/tutorials/getting-started.md) for alternative setup methods.
+
 ## Configuration
 
 Environment variables (see `.env.example`):
@@ -114,24 +119,65 @@ We use the **[Diátaxis](https://diataxis.fr/)** framework for documentation:
 
 See [Architecture Overview](docs/explanation/architecture.md) for system design and [Test Strategy](docs/reference/test-strategy.md) for testing approach.
 
+### Running Tests
+
+We have two test suites:
+
+**1. Main Project Tests (ngit-grasp)**
+
 ```bash
-# Run tests
-cargo test
+# Run unit tests (no external dependencies)
+nix develop -c cargo test --lib
+
+# Run integration tests (tests our relay implementation)
+# First, start ngit-grasp relay in one terminal:
+NGIT_BIND_ADDRESS=127.0.0.1:7000 nix develop -c cargo run
+
+# Then in another terminal, run integration tests:
+nix develop -c cargo test --test announcement_tests --ignored
+
+# Or use the test script (starts relay automatically):
+./test_relay.sh
+```
 
-# Run compliance tests
-cargo test --test compliance
+**2. GRASP Audit Tool (grasp-audit)**
 
+The audit tool tests GRASP compliance of any relay (including ours or external ones).
+
+```bash
+# Enter grasp-audit directory
+cd grasp-audit
+
+# Run unit tests
+nix develop -c cargo test
+
+# Test against our ngit-grasp relay:
+# First, start ngit-grasp (in another terminal):
+cd .. && NGIT_BIND_ADDRESS=127.0.0.1:7000 nix develop -c cargo run
+
+# Then run audit:
+nix develop -c cargo run -- --url ws://127.0.0.1:7000
+
+# Or test against any external relay:
+nix develop -c cargo run -- --url wss://relay.example.com
+```
+
+### Development Commands
+
+```bash
 # Run with logging
-RUST_LOG=debug cargo run
+RUST_LOG=debug nix develop -c cargo run
 
 # Check code
-cargo clippy
-cargo fmt --check
+nix develop -c cargo clippy
+nix develop -c cargo fmt --check
 
-# Generate test coverage
-cargo tarpaulin --out Html
+# Generate test coverage (requires tarpaulin)
+nix develop -c cargo tarpaulin --out Html
 ```
 
+**Note:** Always use `nix develop` to ensure the correct build environment. See [docs/how-to/nix-flakes.md](docs/how-to/nix-flakes.md) for details.
+
 ## Project Structure
 
 ```
-- 
cgit v1.2.3