mirror of
https://github.com/LukasKanka/api_test.git
synced 2026-11-11 06:34:36 +01:00
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>
This commit is contained in:
kankys committed
1 parent
8a66fa2760
commit
55626902fe
3 files changed
+268
-1
No files matched your search
@@ -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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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*
|
||||
@@ -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\""
|
||||
|
||||
Reference in new issue
Block a user