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:
@@ -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
|
||||||
|
|||||||
@@ -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
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
@@ -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
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user