admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add K6 documentation index and navigation guide

Browse Source 
K6_README.md provides:
- Index of three complementary documentation files
- Quick 3-minute start guide
- Test scenarios overview with priorities
- Authentication methods (cookie vs token)
- Endpoint priority matrix (high/medium/low)
- API structure reference
- Rate limits and quota information
- Integration with existing tests (Vitest, Playwright)
- CI/CD integration points
- Cross-reference guide for quick lookup
- Common tasks workflow
- Learning path (beginner → intermediate → advanced)

This serves as the entry point for K6 load testing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Ho Ngoc Hai
2026-04-09 01:36:13 +07:00
parent a5f260ce67
commit ffb6179b65
1 changed files with 404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

404
K6_README.md Normal file
View File

@@ -0,0 +1,404 @@
# K6 Load Testing Documentation for GoodGo Platform
Complete guide to understanding and implementing K6 load tests for the GoodGo Platform API.
---
## 📚 Documentation Files
This directory contains three comprehensive guides for K6 load testing:
### 1. **K6_LOAD_TESTING_GUIDE.md** (Primary Reference)
Comprehensive exploration of the GoodGo Platform API structure for load testing.
**Contents:**
- API module structure (auth, listings, payments, search)
- Detailed endpoint documentation with HTTP methods, rate limits, and auth requirements
- Complete DTO specifications with request/response body shapes
- Database and environment configuration reference
- Existing test setup (Playwright, Vitest, CI/CD)
- Architecture patterns (CQRS, DDD)
- File location quick reference
- K6 implementation recommendations
**When to use:** Deep dives into specific endpoints, understanding authentication flows, checking environment variables
### 2. **K6_ENDPOINTS_SUMMARY.md** (Quick Reference)
Condensed endpoint reference with data shapes for immediate lookup.
**Contents:**
- All endpoints in table format (method, path, auth, rate limit)
- Authentication module (register, login, refresh, profile)
- Listings module (CRUD, moderation, media upload)
- Payments module (create, list, callbacks, refund)
- Search module (full-text, geo)
- Request/response body examples (JSON)
- K6 test scenarios (search, auth, listings, payments, webhooks)
- Rate limits summary
- Authentication flow examples (cookies vs tokens)
**When to use:** Quick lookup of endpoint details, copy-paste example payloads, understanding rate limits
### 3. **K6_QUICK_START.md** (Executable Examples)
Step-by-step guide with ready-to-run K6 scripts and setup instructions.
**Contents:**
- Installation instructions (macOS, Linux, Docker)
- Environment setup (starting API, seeding database)
- Five runnable K6 scripts:
- Search load test (public, high volume)
- Auth load test (rate-limited registration)
- Listing creation (authenticated, quota-gated)
- Payment processing (authenticated)
- All scenarios combined
- CI integration with GitHub Actions
- Report generation options (JSON, Grafana Cloud, CSV)
- Common K6 checks and patterns
- Debugging and troubleshooting
**When to use:** Getting started quickly, running tests immediately, setting up CI/CD
---
## 🚀 Quick Start (3 Minutes)
### 1. Install K6
```bash
brew install k6 # macOS
# or
apt-get install k6 # Linux
```
### 2. Start API & Database
```bash
pnpm install
pnpm db:generate
pnpm db:migrate:dev
pnpm db:seed
pnpm dev
```
### 3. Run a Load Test
```bash
# Copy this from K6_QUICK_START.md Step 3
k6 run load-tests/search.k6.js
```
### 4. View Results
K6 prints a summary to console. For more detailed reports, see K6_QUICK_START.md section on report generation.
---
## 📊 Test Scenarios Implemented
| Scenario | File | Focus | VUs | Duration | Key Endpoints |
|----------|------|-------|-----|----------|--------------|
| Search Load | `load-tests/search.k6.js` | Public search performance | 50 | 4m | `GET /search`, `GET /search/geo` |
| Authentication | `load-tests/auth.k6.js` | Auth throughput & rate limits | 10 | 2m | `POST /auth/register`, `POST /auth/login` |
| Listing Creation | `load-tests/listings.k6.js` | Authenticated listing CRUD | 5 | 2m | `POST /listings`, `GET /listings/:id` |
| Payments | `load-tests/payments.k6.js` | Payment initiation & status | 10 | 2m | `POST /payments`, `GET /payments/:id` |
| Combined | `load-tests/all-scenarios.k6.js` | Realistic mixed load | 50 | 5m | Multiple endpoints |
---
## 🔐 Authentication Methods
### Option 1: Cookie-Based (Recommended for Browser-Like Tests)
```javascript
const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
// Cookies automatically managed by K6
const profileRes = http.get(`${BASE_URL}/auth/profile`);
```
### Option 2: Bearer Token (Recommended for API-Only Tests)
```javascript
const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
const { accessToken } = loginRes.json();
const headers = { Authorization: `Bearer ${accessToken}` };
const profileRes = http.get(`${BASE_URL}/auth/profile`, { headers });
```
See K6_ENDPOINTS_SUMMARY.md for full examples.
---
## 🎯 Key Endpoints by Priority
### High Priority (Core Functionality)
| Endpoint | Priority | Why |
|----------|----------|-----|
| `GET /search` | ⭐⭐⭐ | Public, high-volume query |
| `GET /search/geo` | ⭐⭐⭐ | Geospatial, frequently used |
| `GET /listings` | ⭐⭐⭐ | Public search/filter |
| `GET /listings/:id` | ⭐⭐⭐ | Detail page load |
| `POST /auth/login` | ⭐⭐ | User session creation |
| `POST /auth/register` | ⭐⭐ | Rate-limited, important |
### Medium Priority (Feature-Specific)
| Endpoint | Priority | Why |
|----------|----------|-----|
| `POST /listings` | ⭐⭐ | Quota-gated, authenticated |
| `POST /payments` | ⭐⭐ | External integrations |
| `GET /payments` | ⭐⭐ | User transaction history |
| `POST /payments/callback/:provider` | ⭐⭐ | Webhook handler, critical |
### Low Priority (Admin/Specialized)
| Endpoint | Priority | Why |
|----------|----------|-----|
| `PATCH /listings/:id/moderate` | ⭐ | Admin-only |
| `GET /listings/pending` | ⭐ | Admin-only |
| `POST /search/reindex` | ⭐ | Admin-only, scheduled |
---
## 📍 API Structure at a Glance
```
API Base: http://localhost:3001/api/v1
Modules:
├── /auth # User authentication & profiles
├── /listings # Property CRUD & moderation
├── /search # Full-text & geo search
├── /payments # Payment processing & webhooks
├── /subscriptions # Plans & quotas (not focused for load tests)
├── /admin # Admin operations (low priority for load tests)
└── /analytics # Market data (low priority for load tests)
```
---
## 🗄️ Database Configuration
### Local Development
```bash
DATABASE_URL=postgresql://goodgo:password@localhost:5432/goodgo
REDIS_URL=redis://localhost:6379
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
```
### Test Environment (CI)
```bash
DATABASE_URL=postgresql://goodgo:goodgo_test_secret@localhost:5432/goodgo_test
REDIS_URL=redis://localhost:6379
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
```
See K6_LOAD_TESTING_GUIDE.md for full environment variables.
---
## ⚡ Rate Limits
Respect these limits in your load tests:
| Endpoint | Limit | Window | Action on Exceeded |
|----------|-------|--------|-------------------|
| `/auth/register` | 5 | per hour | Returns 429 |
| `/auth/login` | 5 | per hour | Returns 429 |
| `/auth/refresh` | 5 | per hour | Returns 429 |
| `/payments/callback/*` | 20 | per minute | Returns 429 |
| All others | None | N/A | Quota gates apply for writes |
**K6 Handling:**
```javascript
check(res, {
'status not rate limited': (r) => r.status !== 429,
'status success or expected': (r) => [200, 201, 400, 404].includes(r.status),
});
```
---
## 🏗️ Recommended Test Structure
```
load-tests/
├── search.k6.js # High-volume public search
├── auth.k6.js # Authentication flow with rate limit handling
├── listings.k6.js # Authenticated listing creation
├── payments.k6.js # Payment processing
├── all-scenarios.k6.js # Combined realistic mix
├── helpers/
│ ├── data-generators.js # Generate test data (users, listings)
│ ├── auth-flows.js # Reusable login/register functions
│ └── assertions.js # Custom check functions
└── config.js # Base URL, env, thresholds
```
Example helper structure provided in K6_QUICK_START.md.
---
## 🧪 Integration with Existing Tests
### Complement, Don't Replace
K6 is for **load testing** (performance under concurrent load).
Existing tests serve different purposes:
| Test Type | Tool | Purpose | When |
|-----------|------|---------|------|
| Unit Tests | Vitest | Verify function logic | During development |
| E2E Tests | Playwright | Verify user flows work | Before deployment |
| Load Tests | K6 | Verify performance at scale | Scheduled, on-demand |
### Running All Tests
```bash
# Unit tests (API only)
pnpm test
# E2E tests (API + Web)
pnpm test:e2e
# Load tests (new)
k6 run load-tests/search.k6.js
# All in sequence
pnpm test && pnpm test:e2e && k6 run load-tests/all-scenarios.k6.js
```
---
## 📈 CI/CD Integration
### GitHub Actions Workflow
Create `.github/workflows/load-test.yml` (template in K6_QUICK_START.md section 🔟):
```bash
# Runs on schedule (daily at 2 AM)
# Or manually via workflow_dispatch
# Reports results as artifacts
```
### Manual Reporting
```bash
# Export JSON
k6 run load-tests/search.k6.js --summary-export=results.json
# View CSV (with extension)
k6 run load-tests/search.k6.js --out csv=results.csv
# Upload to Grafana Cloud
K6_CLOUD_TOKEN=xxx k6 run load-tests/search.k6.js --out cloud
```
---
## 🔗 Cross-Reference Guide
### Looking for...?
| Need | Find in |
|------|----------|
| All endpoint URLs & methods | K6_ENDPOINTS_SUMMARY.md |
| Request/response JSON shapes | K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes) |
| DTOs & validation rules | K6_LOAD_TESTING_GUIDE.md (Controllers & DTOs) |
| Rate limit specifics | K6_ENDPOINTS_SUMMARY.md (📌 Important Rate Limits) |
| Authentication flows | K6_ENDPOINTS_SUMMARY.md (🔗 Authentication Flow for K6) |
| Database variables | K6_LOAD_TESTING_GUIDE.md (🗄️ Database & Environment) |
| Ready-to-run scripts | K6_QUICK_START.md (Steps 3-8️⃣) |
| CI/CD setup | K6_QUICK_START.md (Step 🔟) |
| Troubleshooting | K6_QUICK_START.md (✅ Troubleshooting) |
| Architecture details | K6_LOAD_TESTING_GUIDE.md (📊 Architecture Patterns) |
| File locations | K6_LOAD_TESTING_GUIDE.md (📁 File Locations Quick Reference) |
---
## 🛠️ Common Tasks
### Task: Load Test Search Endpoint
1. Read: K6_ENDPOINTS_SUMMARY.md (🔍 Search section)
2. Use: K6_QUICK_START.md (Step 3️⃣ - Search Load Test)
3. Run: `k6 run load-tests/search.k6.js`
### Task: Understand Payment Flow
1. Read: K6_LOAD_TESTING_GUIDE.md (💳 PAYMENTS MODULE)
2. Check: K6_ENDPOINTS_SUMMARY.md (💳 Payments section)
3. Use: K6_QUICK_START.md (Step 7️⃣ - Payment Test)
### Task: Add New Endpoint to Load Tests
1. Find endpoint in: K6_LOAD_TESTING_GUIDE.md or K6_ENDPOINTS_SUMMARY.md
2. Get data shape from: K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes)
3. Check auth from: K6_LOAD_TESTING_GUIDE.md (each module section)
4. Implement using examples in: K6_QUICK_START.md
---
## ✅ Verification Checklist
Before running load tests, verify:
- [ ] API running: `pnpm dev` (port 3001)
- [ ] Database seeded: `pnpm db:seed`
- [ ] K6 installed: `k6 version`
- [ ] Can reach API: `curl http://localhost:3001/api/v1/docs`
- [ ] ENV variables set: `JWT_SECRET`, `CORS_ORIGINS`, etc.
- [ ] Load test file exists: `load-tests/*.k6.js`
- [ ] Test data available: Check seed in `prisma/seed.ts`
---
## 📞 Support & References
### Internal Documentation
- **Full Architecture**: K6_LOAD_TESTING_GUIDE.md
- **Endpoint Reference**: K6_ENDPOINTS_SUMMARY.md
- **Getting Started**: K6_QUICK_START.md
### External Resources
- **K6 Official Docs**: https://k6.io/docs
- **K6 API Reference**: https://k6.io/docs/javascript-api
- **K6 Community**: https://community.k6.io
- **K6 Examples**: https://github.com/grafana/k6-templates
### Project Files
- **API Controllers**: `apps/api/src/modules/*/presentation/controllers/`
- **DTOs**: `apps/api/src/modules/*/presentation/dto/`
- **E2E Tests**: `e2e/api/`
- **Seed Data**: `prisma/seed.ts`
---
## 🎓 Learning Path
### Beginner (30 minutes)
1. Read K6_QUICK_START.md (Steps 1-4)
2. Install K6
3. Run: `k6 run load-tests/search.k6.js`
### Intermediate (1-2 hours)
1. Read K6_ENDPOINTS_SUMMARY.md
2. Understand auth flows
3. Run auth test: `k6 run load-tests/auth.k6.js`
4. Run listing test: `k6 run load-tests/listings.k6.js`
### Advanced (2-4 hours)
1. Read K6_LOAD_TESTING_GUIDE.md completely
2. Review controller implementations in source
3. Create custom load test script
4. Set up CI/CD with GitHub Actions (K6_QUICK_START.md Step 🔟)
5. Generate and analyze reports
---
## 📝 Notes
- **No existing K6 setup** — These docs provide complete guidance
- **Three complementary docs** — Explore different docs for different needs
- **Executable examples** — K6_QUICK_START.md scripts work as-is
- **Rate limits matter** — Consider them in test design
- **Quota gates** — Some operations (listings, payments) are gated by subscription
- **Test data** — Use seed data or generate unique test users per VU
- **Production ready** — Guides follow K6 best practices
---
Generated: 2026-04-09
Last Updated: K6_QUICK_START.md latest