diff --git a/README.md b/README.md index cacddec..1b75e50 100644 --- a/README.md +++ b/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 --- diff --git a/docs/COLECTION_GUIDE.md b/docs/COLECTION_GUIDE.md new file mode 100644 index 0000000..c093bcc --- /dev/null +++ b/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ázvem své nové kolekce +mkdir -p apiTest//Endpoint1 +mkdir -p apiTest//Endpoint2 +``` + +### 2. Přidej konfigurační soubor kolekce +Vytvoř `apiTest//opencollection.yml`: +```yaml +opencollection: 1.0.0 + +info: + name: + 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//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//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/ && 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* \ No newline at end of file diff --git a/package.json b/package.json index 5b3097e..573fc67 100644 --- a/package.json +++ b/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\""