docs: update Bruno terminology to OpenCollection YAML format

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"
This commit is contained in:
2026-02-17 20:24:20 -05:00
parent f859b2714d
commit 105c427544
9 changed files with 34 additions and 34 deletions
+6 -6
View File
@@ -128,7 +128,7 @@ VERIFY → Compile successfully
- ✅ Stop building server binaries - everything goes through containers - ✅ Stop building server binaries - everything goes through containers
### API Changes (Full-Stack Tasks Only) ### 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 - ✅ Tests must be **comprehensive and cover three contexts**: no user, user, and admin
- ✅ Maintain backward compatibility for mobile apps and external consumers - ✅ 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 | | **Quick start/setup** | `README.md` | Installation, environment setup, first-run |
| **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices | | **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices |
| **Bug fixes** | Update relevant `docs/` only if user-visible | Clarifications, troubleshooting additions | | **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**: **Documentation Update Workflow**:
1. **Identify the audience** (end users, developers, API consumers) 1. **Identify the audience** (end users, developers, API consumers)
@@ -212,7 +212,7 @@ VERIFY → Compile successfully
3. **Update documentation** before or with code changes 3. **Update documentation** before or with code changes
4. **Verify documentation renders** at `/docs` endpoint 4. **Verify documentation renders** at `/docs` endpoint
5. **Test search** finds new/updated content 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: <description>` 7. **Commit separately** with clear message: `docs: <description>`
**When in doubt**: **When in doubt**:
@@ -312,7 +312,7 @@ git checkout -- internal/handlers/auth.go
- [ ] New endpoints → Create new `.md` file in `docs/developer/api/` - [ ] New endpoints → Create new `.md` file in `docs/developer/api/`
- [ ] API behavior → Update existing `docs/developer/api/` files - [ ] API behavior → Update existing `docs/developer/api/` files
- [ ] Breaking changes → Both `README.md` + relevant `docs/` - [ ] 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) ### During Schema Changes (Full-Stack Only)
- [ ] Read current schema completely - [ ] Read current schema completely
@@ -336,7 +336,7 @@ git checkout -- internal/handlers/auth.go
- [ ] Verify database has new schema (check column types, indexes, etc.) - [ ] Verify database has new schema (check column types, indexes, etc.)
### After API Changes ### After API Changes
- [ ] Create/update Bruno DSL .bru requests - [ ] Create/update Bruno OpenCollection YAML requests
- [ ] Test with no user context - [ ] Test with no user context
- [ ] Test with regular user context - [ ] Test with regular user context
- [ ] Test with admin context - [ ] Test with admin context
@@ -352,7 +352,7 @@ git checkout -- internal/handlers/auth.go
- [ ] Verify logical commit structure - [ ] Verify logical commit structure
- [ ] **Update documentation** (see Documentation section): - [ ] **Update documentation** (see Documentation section):
- [ ] User-facing changes → `docs/user/` - [ ] 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` - [ ] Setup/onboarding → `README.md`
- [ ] Development changes → `docs/contributing/` - [ ] Development changes → `docs/contributing/`
- [ ] **Verify docs render** at `/docs` endpoint - [ ] **Verify docs render** at `/docs` endpoint
+1 -1
View File
@@ -133,7 +133,7 @@ make test-all
# Run integration tests (with test mode) # Run integration tests (with test mode)
make test-integration make test-integration
# Run Bruno API tests # Run Bruno OpenCollection YAML API tests
npm install -g @usebruno/cli npm install -g @usebruno/cli
bruno run bruno run
``` ```
+2 -2
View File
@@ -20,7 +20,7 @@ This is the primary test user used in most integration tests.
**Used in:** **Used in:**
- Go Tests: `cmd/server/tests/test_helpers.go` (getTestUserID, loginTestUser) - 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:** **Notes:**
- Automatically created if doesn't exist - Automatically created if doesn't exist
@@ -58,7 +58,7 @@ Used for testing admin creation restrictions and multi-admin scenarios.
``` ```
**Used in:** **Used in:**
- Bruno: `user/admin/Register Admin User.bru` - Bruno: `user/admin/Register Admin User.yml`
## Test Libraries ## Test Libraries
+3 -3
View File
@@ -1,7 +1,7 @@
opencollection: 1.0.0 opencollection: 1.0.0
info: info:
name: Untitled Collection name: Bookhoard
config: config:
proxy: proxy:
inherit: true inherit: true
@@ -21,8 +21,8 @@ request:
docs: docs:
content: |- content: |-
# Bruno API Tests for Bookhoard # Bruno OpenCollection YAML API Tests for Bookhoard
This directory contains Bruno collection for testing the Bookhoard API with comprehensive REST documentation. This directory contains Bruno OpenCollection YAML format tests for testing the Bookhoard API with comprehensive REST documentation.
Setup Setup
1. Install Bruno: https://www.usebruno.com/ 1. Install Bruno: https://www.usebruno.com/
2. Open Bruno and import this collection folder 2. Open Bruno and import this collection folder
+1 -1
View File
@@ -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 go test ./cmd/server/tests -run TestAuth -v
``` ```
### API Testing with Bruno ### API Testing with Bruno OpenCollection YAML
```bash ```bash
# Install Bruno CLI # Install Bruno CLI
+2 -2
View File
@@ -1606,10 +1606,10 @@ bruno/
├── sync-kobo/ # Kobo sync protocol ├── sync-kobo/ # Kobo sync protocol
├── conflicts/ # Conflict resolution ├── conflicts/ # Conflict resolution
├── queue/ # Sync queue management ├── 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: Install Bruno CLI:
```bash ```bash
+11 -11
View File
@@ -467,20 +467,20 @@ X-RateLimit-Reset: 1643723400
--- ---
## Bruno Tests ## Bruno OpenCollection YAML Tests
Complete API tests available in `bruno/collections/`: Complete API tests available in `bruno/collections/`:
- `Get Collections.bru` - `Get Collections.yml`
- `Create Collection.bru` - `Create Collection.yml`
- `Get Collection.bru` - `Get Collection.yml`
- `Update Collection.bru` - `Update Collection.yml`
- `Delete Collection.bru` - `Delete Collection.yml`
- `Add Books to Collection.bru` - `Add Books to Collection.yml`
- `Remove Book from Collection.bru` - `Remove Book from Collection.yml`
- `Get Book Collections.bru` - `Get Book Collections.yml`
- `Test Collection Rules.bru` - `Test Collection Rules.yml`
- `Bulk Remove Books.bru` - `Bulk Remove Books.yml`
Run tests: Run tests:
```bash ```bash
+6 -6
View File
@@ -259,22 +259,22 @@ templates/... (truncated, first 10 shown)
- `make verify-quick`: Runs critical-only validation - `make verify-quick`: Runs critical-only validation
- Fixed naming confusion (previously ran quick version for both targets) - Fixed naming confusion (previously ran quick version for both targets)
### Bruno API Tests Validation: ### Bruno OpenCollection YAML Validation:
- Counts Bruno `.bru` test files in `bruno/` directory - Counts Bruno OpenCollection YAML `.yml` test files in `bruno/` directory
- Compares against API documentation file count in `docs/api/` - Compares against API documentation file count in `docs/api/`
- Flags insufficient coverage for human review - Flags insufficient coverage for human review
- Ensures API documentation and test coverage stay synchronized - Ensures API documentation and test coverage stay synchronized
## Bruno API Tests Explained ## Bruno OpenCollection YAML Explained
### Purpose: ### 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 - API requests and responses
- Test cases and validation - Test cases and validation
- Contract testing examples - Contract testing examples
### Verification Logic: ### 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 2. **Counts API Docs**: Scans `docs/api/` for `.md` files
3. **Compares Coverage**: Ensures test files >= documentation files 3. **Compares Coverage**: Ensures test files >= documentation files
4. **Flags Gaps**: Human review for insufficient test coverage 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: ### Example Scenario:
``` ```
Developer adds: docs/api/users/login.md 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 Verification catches: API docs exist but no test file
``` ```
+2 -2
View File
@@ -477,8 +477,8 @@ fi
############################################################################### ###############################################################################
section "Documentation: Bruno API Tests" section "Documentation: Bruno API Tests"
echo "Checking Bruno API test files..." echo "Checking Bruno OpenCollection YAML test files..."
BRUNO_FILES=$(find bruno -name "*.bru" 2>/dev/null | wc -l) BRUNO_FILES=$(find bruno -name "*.yml" 2>/dev/null | wc -l)
if [ "$BRUNO_FILES" -gt 0 ]; then if [ "$BRUNO_FILES" -gt 0 ]; then
success_msg "Found $BRUNO_FILES Bruno test files" success_msg "Found $BRUNO_FILES Bruno test files"
else else