Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: update Bruno terminology to OpenCollection YAML format

Browse Source 
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:
john-okeefe
2026-02-17 20:24:20 -05:00
parent f859b2714d
commit 105c427544
9 changed files with 34 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROJECT_GUIDELINES.md
+6 -6
View File
@@ -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: <description>`
**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
README.md
+1 -1
View File
@@ -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
```
TEST_DATA.md
+2 -2
View File
@@ -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
bruno/opencollection.yml
+3 -3
View File
@@ -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
docs/contributing/development.md
+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
```
### API Testing with Bruno
### API Testing with Bruno OpenCollection YAML
```bash
# Install Bruno CLI
docs/developer/api-reference.md
+2 -2
View File
@@ -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
docs/developer/collections-api.md
+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/`:
- `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
scripts/README.md
+6 -6
View File
@@ -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
```
scripts/verify-guidelines.sh
+2 -2
View File
@@ -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