From 105c427544f0e56e17b1959e02453615276b42bc Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Tue, 17 Feb 2026 20:24:20 -0500 Subject: [PATCH] docs: update Bruno terminology to OpenCollection YAML format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update all references from "Bruno DSL .bru files" to "Bruno OpenCollection YAML .yml files" to reflect the current Bruno format. This includes: - PROJECT_GUIDELINES.md: Update API testing requirements - README.md: Update command examples - TEST_DATA.md: Update test data references - docs/contributing/development.md: Update API testing section - docs/developer/api-reference.md: Update Bruno testing documentation - docs/developer/collections-api.md: Update test file references - scripts/README.md: Update validation script documentation - scripts/verify-guidelines.sh: Update file extension check (.bru → .yml) - bruno/opencollection.yml: Rename collection from "Untitled Collection" to "Bookhoard" --- PROJECT_GUIDELINES.md | 12 ++++++------ README.md | 2 +- TEST_DATA.md | 4 ++-- bruno/opencollection.yml | 6 +++--- docs/contributing/development.md | 2 +- docs/developer/api-reference.md | 4 ++-- docs/developer/collections-api.md | 22 +++++++++++----------- scripts/README.md | 12 ++++++------ scripts/verify-guidelines.sh | 4 ++-- 9 files changed, 34 insertions(+), 34 deletions(-) diff --git a/PROJECT_GUIDELINES.md b/PROJECT_GUIDELINES.md index f8eeea8..3c1546f 100644 --- a/PROJECT_GUIDELINES.md +++ b/PROJECT_GUIDELINES.md @@ -128,7 +128,7 @@ VERIFY → Compile successfully - ✅ Stop building server binaries - everything goes through containers ### API Changes (Full-Stack Tasks Only) -- ✅ Include **Bruno DSL .bru requests** with all API documentation +- ✅ Include **Bruno OpenCollection YAML requests** with all API documentation - ✅ Tests must be **comprehensive and cover three contexts**: no user, user, and admin - ✅ Maintain backward compatibility for mobile apps and external consumers @@ -204,7 +204,7 @@ VERIFY → Compile successfully | **Quick start/setup** | `README.md` | Installation, environment setup, first-run | | **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices | | **Bug fixes** | Update relevant `docs/` only if user-visible | Clarifications, troubleshooting additions | -| **Bruno API tests** | `.bru` files alongside code | API contract testing, examples | +| **Bruno OpenCollection YAML tests** | `.yml` files in bruno folder in appropriate folder/sub-folder | API contract testing, examples | **Documentation Update Workflow**: 1. **Identify the audience** (end users, developers, API consumers) @@ -212,7 +212,7 @@ VERIFY → Compile successfully 3. **Update documentation** before or with code changes 4. **Verify documentation renders** at `/docs` endpoint 5. **Test search** finds new/updated content -6. **For API changes**: Update both `docs/developer/api/` files AND Bruno `.bru` files +6. **For API changes**: Update both `docs/developer/api/` files AND Bruno OpenCollection YAML `.yml` files 7. **Commit separately** with clear message: `docs: ` **When in doubt**: @@ -312,7 +312,7 @@ git checkout -- internal/handlers/auth.go - [ ] New endpoints → Create new `.md` file in `docs/developer/api/` - [ ] API behavior → Update existing `docs/developer/api/` files - [ ] Breaking changes → Both `README.md` + relevant `docs/` - - [ ] Bruno `.bru` files → Update/create alongside API changes + - [ ] Bruno OpenCollection YAML `.yml` files → Update/create alongside API changes ### During Schema Changes (Full-Stack Only) - [ ] Read current schema completely @@ -336,7 +336,7 @@ git checkout -- internal/handlers/auth.go - [ ] Verify database has new schema (check column types, indexes, etc.) ### After API Changes -- [ ] Create/update Bruno DSL .bru requests +- [ ] Create/update Bruno OpenCollection YAML requests - [ ] Test with no user context - [ ] Test with regular user context - [ ] Test with admin context @@ -352,7 +352,7 @@ git checkout -- internal/handlers/auth.go - [ ] Verify logical commit structure - [ ] **Update documentation** (see Documentation section): - [ ] User-facing changes → `docs/user/` - - [ ] API changes → `docs/developer/api/` + Bruno `.bru` files + - [ ] API changes → `docs/developer/api/` + Bruno OpenCollection YAML `.yml` files - [ ] Setup/onboarding → `README.md` - [ ] Development changes → `docs/contributing/` - [ ] **Verify docs render** at `/docs` endpoint diff --git a/README.md b/README.md index 161d35f..74af2cb 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ make test-all # Run integration tests (with test mode) make test-integration -# Run Bruno API tests +# Run Bruno OpenCollection YAML API tests npm install -g @usebruno/cli bruno run ``` diff --git a/TEST_DATA.md b/TEST_DATA.md index 3eda621..01fbcb7 100644 --- a/TEST_DATA.md +++ b/TEST_DATA.md @@ -20,7 +20,7 @@ This is the primary test user used in most integration tests. **Used in:** - Go Tests: `cmd/server/tests/test_helpers.go` (getTestUserID, loginTestUser) -- Bruno: `user/auth/Login User.bru`, `user/auth/Register User.bru` +- Bruno: `user/auth/Login User.yml`, `user/auth/Register User.yml` **Notes:** - Automatically created if doesn't exist @@ -58,7 +58,7 @@ Used for testing admin creation restrictions and multi-admin scenarios. ``` **Used in:** -- Bruno: `user/admin/Register Admin User.bru` +- Bruno: `user/admin/Register Admin User.yml` ## Test Libraries diff --git a/bruno/opencollection.yml b/bruno/opencollection.yml index 56977b2..ec6a8c6 100644 --- a/bruno/opencollection.yml +++ b/bruno/opencollection.yml @@ -1,7 +1,7 @@ opencollection: 1.0.0 info: - name: Untitled Collection + name: Bookhoard config: proxy: inherit: true @@ -21,8 +21,8 @@ request: docs: content: |- - # Bruno API Tests for Bookhoard - This directory contains Bruno collection for testing the Bookhoard API with comprehensive REST documentation. + # Bruno OpenCollection YAML API Tests for Bookhoard + This directory contains Bruno OpenCollection YAML format tests for testing the Bookhoard API with comprehensive REST documentation. Setup 1. Install Bruno: https://www.usebruno.com/ 2. Open Bruno and import this collection folder diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 25e6861..2c4ca19 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -256,7 +256,7 @@ TEST_MODE=true RATE_LIMIT_ENABLED=false go test ./cmd/server/tests -v go test ./cmd/server/tests -run TestAuth -v ``` -### API Testing with Bruno +### API Testing with Bruno OpenCollection YAML ```bash # Install Bruno CLI diff --git a/docs/developer/api-reference.md b/docs/developer/api-reference.md index 3309863..bdf4ebc 100644 --- a/docs/developer/api-reference.md +++ b/docs/developer/api-reference.md @@ -1606,10 +1606,10 @@ bruno/ ├── sync-kobo/ # Kobo sync protocol ├── conflicts/ # Conflict resolution ├── queue/ # Sync queue management -└── collection.bru # Main collection file +└── collection.yml # Main collection file ``` -## Testing with Bruno +## Testing with Bruno OpenCollection YAML Install Bruno CLI: ```bash diff --git a/docs/developer/collections-api.md b/docs/developer/collections-api.md index 82b2e3f..7d0cefc 100644 --- a/docs/developer/collections-api.md +++ b/docs/developer/collections-api.md @@ -467,20 +467,20 @@ X-RateLimit-Reset: 1643723400 --- -## Bruno Tests +## Bruno OpenCollection YAML Tests Complete API tests available in `bruno/collections/`: -- `Get Collections.bru` -- `Create Collection.bru` -- `Get Collection.bru` -- `Update Collection.bru` -- `Delete Collection.bru` -- `Add Books to Collection.bru` -- `Remove Book from Collection.bru` -- `Get Book Collections.bru` -- `Test Collection Rules.bru` -- `Bulk Remove Books.bru` +- `Get Collections.yml` +- `Create Collection.yml` +- `Get Collection.yml` +- `Update Collection.yml` +- `Delete Collection.yml` +- `Add Books to Collection.yml` +- `Remove Book from Collection.yml` +- `Get Book Collections.yml` +- `Test Collection Rules.yml` +- `Bulk Remove Books.yml` Run tests: ```bash diff --git a/scripts/README.md b/scripts/README.md index c555473..728e4c3 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -259,22 +259,22 @@ templates/... (truncated, first 10 shown) - `make verify-quick`: Runs critical-only validation - Fixed naming confusion (previously ran quick version for both targets) -### Bruno API Tests Validation: -- Counts Bruno `.bru` test files in `bruno/` directory +### Bruno OpenCollection YAML Validation: +- Counts Bruno OpenCollection YAML `.yml` test files in `bruno/` directory - Compares against API documentation file count in `docs/api/` - Flags insufficient coverage for human review - Ensures API documentation and test coverage stay synchronized -## Bruno API Tests Explained +## Bruno OpenCollection YAML Explained ### Purpose: -Bruno v3.0 is an API testing tool that uses `.bru` files to define: +Bruno is an API testing tool that uses OpenCollection YAML format (`.yml` files) to define: - API requests and responses - Test cases and validation - Contract testing examples ### Verification Logic: -1. **Counts Test Files**: Scans `bruno/` directory for `.bru` files +1. **Counts Test Files**: Scans `bruno/` directory for `.yml` files 2. **Counts API Docs**: Scans `docs/api/` for `.md` files 3. **Compares Coverage**: Ensures test files >= documentation files 4. **Flags Gaps**: Human review for insufficient test coverage @@ -282,7 +282,7 @@ Bruno v3.0 is an API testing tool that uses `.bru` files to define: ### Example Scenario: ``` Developer adds: docs/api/users/login.md -Should also add: bruno/user/auth/Login User.bru +Should also add: bruno/user/auth/Login User.yml Verification catches: API docs exist but no test file ``` diff --git a/scripts/verify-guidelines.sh b/scripts/verify-guidelines.sh index e3eb6c8..cdd070d 100755 --- a/scripts/verify-guidelines.sh +++ b/scripts/verify-guidelines.sh @@ -477,8 +477,8 @@ fi ############################################################################### section "Documentation: Bruno API Tests" -echo "Checking Bruno API test files..." -BRUNO_FILES=$(find bruno -name "*.bru" 2>/dev/null | wc -l) +echo "Checking Bruno OpenCollection YAML test files..." +BRUNO_FILES=$(find bruno -name "*.yml" 2>/dev/null | wc -l) if [ "$BRUNO_FILES" -gt 0 ]; then success_msg "Found $BRUNO_FILES Bruno test files" else