docs: add collection guide and test:all:with-backend script

- Add docs/COLECTION_GUIDE.md with complete guide for creating new collections
- Add test:all:with-backend script for automatic backend + tests execution
- Update README.md with JsonPlaceholder reference and new script info

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

README.md

@@ -11,6 +11,7 @@ Tento projekt slouží jako **playground** pro vývoj, testování a výuku API
 | Služba | Backend | Frontend | Testy | Dokumentace |
 |--------|---------|----------|-------|--------------|
 | **PotterAPI** | [`backends/potter-api`](./backends/potter-api) | [`backends/potter-api/frontend`](./backends/potter-api/frontend) | [`apiTest/PotterAPI`](./apiTest/PotterAPI) | [bruno_test_scenario.md](./backends/potter-api/bruno_test_scenario.md) |
+| **JsonPlaceholder** | ❌ Veřejné API | ❌ | [`apiTest/JsonPlaceholder`](./apiTest/JsonPlaceholder) | - |
 
 ---
 
@@ -51,9 +52,12 @@ Frontend bude dostupný na **`http://localhost:8080`**.
 ### 4️⃣ Spuštění testů
 
 ```bash
-# Spuštění všech testů
+# Spuštění všech testů (vyžaduje běžící backend pro PotterAPI)
 npm run test:all
 
+# Spuštění všech testů + spuštění backendu (automaticky)
+npm run test:all:with-backend
+
 # Spuštění pouze PotterAPI testů
 npm run test:potter
 
@@ -61,6 +65,10 @@ npm run test:potter
 npm run test:watch
 ```
 
+> ⚠️ **Poznámka:** Testy pro **PotterAPI** vyžadují běžící backend na `localhost:3000`. 
+> Testy pro **JsonPlaceholder** fungují bez backendu (používají veřejné API).
+> Použij `npm run test:all:with-backend` pro automatické spuštění backendu i testů.
+
 ---
 
 ## 📁 Struktura monorepa
@@ -169,6 +177,8 @@ Soubor: [`.github/workflows/api-tests.yml`](./.github/workflows/api-tests.yml)
 ## 📄 Dokumentace
 
 - [PotterAPI – Testovací scénáře](./backends/potter-api/bruno_test_scenario.md) – Detailní průvodce testováním PotterAPI
+- [Průvodce vytvářením kolekcí](./docs/COLECTION_GUIDE.md) – Jak přidat novou testovací kolekci
+- [Architektura monorepa](./docs/) – Další dokumentace
 
 ---
 

docs/COLECTION_GUIDE.md

@@ -0,0 +1,256 @@
+# 📚 Průvodce vytvářením nové testovací kolekce
+
+Tento návod vysvětluje, jak přidat **novou testovací kolekci** do `apiTest/` tak, aby byla **automaticky detekována** jak lokálně (`npm run test:all`), tak v CI/CD pipeline.
+
+---
+
+## 🎯 Rychlý start
+
+### 1. Vytvoř základní strukturu
+```bash
+# Nahraď <název-kolekce> názvem své nové kolekce
+mkdir -p apiTest/<název-kolekce>/Endpoint1
+mkdir -p apiTest/<název-kolekce>/Endpoint2
+```
+
+### 2. Přidej konfigurační soubor kolekce
+Vytvoř `apiTest/<název-kolekce>/opencollection.yml`:
+```yaml
+opencollection: 1.0.0
+
+info:
+  name: <Název Tvé Kolekce>
+  type: collection
+
+request:
+  auth: inherit
+
+bundled: false
+
+extensions:
+  bruno:
+    ignore:
+      - node_modules
+      - .git
+```
+
+### 3. Vytvoř složky pro endpointy
+Pro každý typ požadavků vytvoř složku s `folder.yml`:
+```yaml
+# apiTest/<název-kolekce>/Endpoint1/folder.yml
+info:
+  name: Endpoint1
+  type: folder
+  seq: 1
+
+request:
+  auth: inherit
+```
+
+### 4. Přidej testovací soubory
+Vytvoř `.yml` soubor pro každý test:
+```yaml
+# apiTest/<název-kolekce>/Endpoint1/Název-testu.yml
+info:
+  name: Název testu
+  type: http
+  seq: 1
+
+http:
+  method: GET  # nebo POST, PUT, DELETE
+  url: https://api.example.com/endpoint
+  auth: inherit
+  headers:
+    - name: Content-Type
+      value: application/json
+
+runtime:
+  scripts:
+    - type: tests
+      code: |-
+        const status = res.getStatus();
+        const body = res.getBody();
+        
+        test("Status code is 200", function() {
+          expect(status).to.equal(200);
+        });
+        
+        test("Response is valid", function() {
+          expect(body).to.not.be.empty;
+        });
+
+settings:
+  encodeUrl: true
+  timeout: 10000
+  followRedirects: true
+  maxRedirects: 5
+```
+
+---
+
+## 📁 Příklady struktury
+
+### Příklad 1: Veřejné API (bez backendu)
+```
+apiTest/JsonPlaceholder/
+├── opencollection.yml
+├── Users/
+│   ├── folder.yml
+│   └── Get-all-users.yml
+└── Posts/
+    ├── folder.yml
+    ├── Get-post-by-ID.yml
+    └── Create-new-post.yml
+```
+
+### Příklad 2: Lokální API (s backendem)
+```
+apiTest/MyLocalAPI/
+├── opencollection.yml
+├── GET/
+│   ├── folder.yml
+│   ├── Get-all-items.yml
+│   └── Get-item-by-ID.yml
+└── POST/
+    ├── folder.yml
+    └── Create-new-item.yml
+```
+
+---
+
+## 🚀 Automatická detekce
+
+### Lokálně
+Skript `npm run test:all` **automaticky najde všechny kolekce** v `apiTest/` a spustí jejich testy.
+
+### V CI/CD (GitHub Actions)
+Pipeline používá stejný princip a spustí testy pro všechny kolekce.
+
+---
+
+## ⚙️ Důležité poznámky
+
+### 1. Bruno CLI požadavky
+- **Kořenová složka kolekce** musí obsahovat `opencollection.yml`
+- **Každá kolekce** musí být ve své vlastní složce v `apiTest/`
+- **Bruno CLI** musí být spuštěn **z kořenové složky kolekce**
+
+### 2. Typy API
+
+| Typ | Příklad | Vyžaduje backend? | URL příklad |
+|-----|---------|-------------------|-------------|
+| **Veřejné API** | JSONPlaceholder, OpenWeather | ❌ Ne | `https://api.example.com` |
+| **Lokální API** | PotterAPI | ✅ Ano | `http://localhost:3000` |
+| **Mock API** | json-server, MSW | ✅/❌ | `http://localhost:3001` |
+
+### 3. Backend závislosti
+Pokud testy vyžadují místní backend:
+- Ujistěte se, že backend běží před spuštěním testů
+- Použijte `npm run test:all:with-backend` pro automatické spuštění
+- Nebo spusťte backend ručně: `cd backends/<služba> && npm start`
+
+---
+
+## 📝 Kompletní příklad: OpenWeather API
+
+### 1. Vytvoř strukturu
+```bash
+mkdir -p apiTest/OpenWeather/Current
+```
+
+### 2. Vytvoř opencollection.yml
+```yaml
+opencollection: 1.0.0
+info:
+  name: OpenWeather
+request:
+  auth: inherit
+bundled: false
+```
+
+### 3. Vytvoř složku pro endpoint
+```yaml
+# apiTest/OpenWeather/Current/folder.yml
+info:
+  name: Current Weather
+  type: folder
+  seq: 1
+request:
+  auth: inherit
+```
+
+### 4. Vytvoř test
+```yaml
+# apiTest/OpenWeather/Current/Get-current-weather.yml
+info:
+  name: Get current weather by city
+  type: http
+  seq: 1
+
+http:
+  method: GET
+  url: https://api.openweathermap.org/data/2.5/weather
+  params:
+    - name: q
+      value: London
+      type: query
+    - name: appid
+      value: YOUR_API_KEY
+      type: query
+  auth: inherit
+
+runtime:
+  scripts:
+    - type: tests
+      code: |-
+        test("Status code is 200", function() {
+          expect(res.getStatus()).to.equal(200);
+        });
+        
+        test("Response has weather data", function() {
+          expect(res.getBody()).to.have.property('weather');
+        });
+
+settings:
+  encodeUrl: true
+  timeout: 10000
+```
+
+---
+
+## 🔧 Řešení problémů
+
+### ❌ Problém: "You can run only at the root of a collection"
+**Příčina:** Bruno CLI je spuštěn z nesprávného adresáře.
+
+**Řešení:** Spouštěj vždy z kořenové složky kolekce (kde je `opencollection.yml`)
+
+### ❌ Problém: Testy pro lokální API selhávají
+**Příčina:** Backend není spuštěn.
+
+**Řešení:** Použij `npm run test:all:with-backend` nebo spusť backend ručně
+
+### ❌ Problém: "Path not found"
+**Příčina:** Špatná cesta k testu.
+
+**Řešení:** Zkontroluj cesty a existenci všech souborů
+
+---
+
+## 💡 Tipy
+
+1. **Nazví složky konvenčně:** Používej `-` místo mezer
+2. **Sekvence testů:** Používej `seq:` pro určení pořadí
+3. **Dokumentace:** Přidej `README.md` do každé nové kolekce
+4. **Testuj postupně:** Začni s jednoduchými testy a přidávej komplexnější
+
+---
+
+## 📚 Další zdroje
+
+- [Bruno Dokumentace](https://www.usebruno.com/docs)
+- [Chai Assertion Library](https://www.chaijs.com/)
+
+---
+
+*Poslední aktualizace: 15. září 2026*

package.json

@@ -15,6 +15,7 @@
     "start:potter-api": "cd backends/potter-api && npm start",
     "start:potter-fe": "cd backends/potter-api/frontend && npm run serve",
     "test:all": "for dir in $(find apiTest -mindepth 1 -maxdepth 1 -type d ! -name \"node_modules\" ! -name \".git\" | sort); do cd \"$dir\" && npx @usebruno/cli run -r && cd ../.. || exit 1; done",
+    "test:all:with-backend": "cd backends/potter-api && npm install 2>/dev/null; PORT=3000 node app.js > /tmp/bruno-server.log 2>&1 & sleep 3 && cd ../.. && npm run test:all && pkill -f \"node app.js\" 2>/dev/null || true",
     "test:potter": "cd apiTest/PotterAPI && npx @usebruno/cli run -r",
     "test:watch": "cd apiTest/PotterAPI && npx @usebruno/cli run -r --watch",
     "lint": "echo \"Linting all workspaces\""