diff --git a/docs/testing-guide-v1.26.md b/docs/testing-guide-v1.26.md new file mode 100644 index 0000000000..dcef35181a --- /dev/null +++ b/docs/testing-guide-v1.26.md @@ -0,0 +1,508 @@ +# Testing Guide for Gitea v1.26.0 + +## Overview + +This guide covers testing the new features in v1.26.0 before production deployment: +- Phase 3: Organization Public Profile +- Phase 4: Gitea Pages +- Phase 5: Wiki V2 API + +--- + +## 1. Test Environment Setup + +### Option A: Docker Test Instance + +```bash +# Create isolated test environment +mkdir gitea-test && cd gitea-test + +# Create docker-compose.yml +cat > docker-compose.yml << 'EOF' +version: "3" +services: + gitea: + image: gitea/gitea:1.26.0 + container_name: gitea-test + environment: + - USER_UID=1000 + - USER_GID=1000 + - GITEA__database__DB_TYPE=sqlite3 + - GITEA__server__ROOT_URL=http://localhost:3000/ + volumes: + - ./gitea-data:/data + ports: + - "3000:3000" + - "2222:22" +EOF + +# Start test instance +docker-compose up -d + +# View logs +docker-compose logs -f gitea +``` + +### Option B: Local Binary Test + +```bash +# Build with test tags +make build TAGS="bindata sqlite sqlite_unlock_notify" + +# Create test directory +mkdir -p /tmp/gitea-test/{data,repos,log} + +# Run with test config +./gitea web --config /tmp/gitea-test/app.ini +``` + +### Test Database + +For testing, use SQLite to avoid affecting production databases: + +```ini +# /tmp/gitea-test/app.ini +[database] +DB_TYPE = sqlite3 +PATH = /tmp/gitea-test/data/gitea.db +``` + +--- + +## 2. Automated Tests + +### Run Existing Test Suite + +```bash +# Unit tests +make test + +# Integration tests (requires test database) +make test-sqlite + +# Specific package tests +go test -v ./services/wiki/... +go test -v ./models/repo/... +go test -v ./routers/api/v2/... +``` + +### New Test Files to Create + +#### Wiki V2 API Tests + +```go +// routers/api/v2/wiki_test.go +package v2 + +import ( + "net/http" + "testing" + + "code.gitea.io/gitea/models/unittest" + "code.gitea.io/gitea/tests" +) + +func TestWikiV2API(t *testing.T) { + defer tests.PrepareTestEnv(t)() + + // Test list pages + t.Run("ListPages", func(t *testing.T) { + req := NewRequest(t, "GET", "/api/v2/repos/user2/repo1/wiki/pages") + resp := MakeRequest(t, req, http.StatusOK) + // Assert response structure + }) + + // Test create page + t.Run("CreatePage", func(t *testing.T) { + req := NewRequestWithJSON(t, "POST", "/api/v2/repos/user2/repo1/wiki/pages", map[string]string{ + "name": "Test-Page", + "content": "# Test\n\nThis is a test page.", + }) + AddTokenAuth(req, "user2") + resp := MakeRequest(t, req, http.StatusOK) + // Assert page created + }) + + // Test search + t.Run("Search", func(t *testing.T) { + req := NewRequest(t, "GET", "/api/v2/repos/user2/repo1/wiki/search?q=test") + resp := MakeRequest(t, req, http.StatusOK) + // Assert search results + }) +} +``` + +--- + +## 3. Manual Testing Checklist + +### Phase 3: Organization Profile + +#### Setup +- [ ] Create test organization: `test-org` +- [ ] Create 5+ test repositories in the organization +- [ ] Add 3+ members with different roles (Owner, Admin, Member) + +#### Pinned Repositories +- [ ] Pin a repository via API: `POST /api/v1/orgs/test-org/pinned` +- [ ] Verify pinned repo appears on org profile page +- [ ] Create a pinned group: `POST /api/v1/orgs/test-org/pinned/groups` +- [ ] Add repos to the group +- [ ] Reorder pinned repos via API +- [ ] Unpin a repository +- [ ] Delete a pinned group + +#### Public Members +- [ ] Set member as public via API +- [ ] Verify member appears on org profile +- [ ] Check role display (Owner/Admin/Member) +- [ ] Remove public visibility +- [ ] Verify "and X more" overflow works + +### Phase 4: Gitea Pages + +#### Setup +- [ ] Create test repository: `test-org/pages-test` +- [ ] Add `.gitea/landing.yaml` configuration file +- [ ] Add README.md with content + +#### Templates +- [ ] Test Simple template +- [ ] Test Documentation template (add `/docs` folder) +- [ ] Test Product template (add features config) +- [ ] Test Portfolio template (add `/gallery` folder) + +#### Settings UI +- [ ] Navigate to repo Settings → Pages +- [ ] Enable pages +- [ ] Select different templates +- [ ] Verify landing page renders at `/{owner}/{repo}/pages` + +#### Custom Domains (if configured) +- [ ] Add custom domain via API +- [ ] Check verification token generated +- [ ] Test domain verification flow + +### Phase 5: Wiki V2 API + +#### Setup +- [ ] Create test repository with wiki enabled +- [ ] Create initial wiki pages via web UI + +#### CRUD Operations +```bash +# Set variables +TOKEN="your-test-token" +BASE="http://localhost:3000/api/v2/repos/test-org/test-repo/wiki" + +# List pages +curl -H "Authorization: token $TOKEN" "$BASE/pages" + +# Get single page +curl -H "Authorization: token $TOKEN" "$BASE/pages/Home" + +# Create page +curl -X POST -H "Authorization: token $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name":"Test-Page","content":"# Test\n\nContent here."}' \ + "$BASE/pages" + +# Update page +curl -X PUT -H "Authorization: token $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"content":"# Updated\n\nNew content."}' \ + "$BASE/pages/Test-Page" + +# Delete page +curl -X DELETE -H "Authorization: token $TOKEN" "$BASE/pages/Test-Page" +``` + +#### Search +```bash +# Search wiki +curl -H "Authorization: token $TOKEN" "$BASE/search?q=installation" +``` + +#### Graph & Stats +```bash +# Get link graph +curl -H "Authorization: token $TOKEN" "$BASE/graph" + +# Get statistics +curl -H "Authorization: token $TOKEN" "$BASE/stats" +``` + +#### Verify Response Structure +- [ ] `content` field contains raw markdown +- [ ] `content_html` field contains rendered HTML +- [ ] `links_out` contains outgoing wiki links +- [ ] `links_in` contains incoming links +- [ ] `word_count` is accurate +- [ ] `last_commit` has correct author info + +--- + +## 4. Regression Testing + +### Critical Paths to Verify + +These existing features MUST still work: + +#### Repository Operations +- [ ] Clone repository (HTTP and SSH) +- [ ] Push commits +- [ ] Create branches +- [ ] Create tags +- [ ] Pull requests work +- [ ] Merge operations work + +#### Wiki (V1 - Existing) +- [ ] Existing wiki pages load +- [ ] Create page via web UI +- [ ] Edit page via web UI +- [ ] Delete page via web UI +- [ ] V1 API endpoints still work: + - `GET /api/v1/repos/{owner}/{repo}/wiki/pages` + - `GET /api/v1/repos/{owner}/{repo}/wiki/page/{pageName}` + +#### Organizations +- [ ] Create organization +- [ ] Add/remove members +- [ ] Team management +- [ ] Repository creation in org + +#### User Operations +- [ ] Login/logout +- [ ] Profile settings +- [ ] SSH key management +- [ ] Access tokens + +--- + +## 5. Load Testing + +### Wiki Search Performance + +```bash +# Install hey (HTTP load generator) +go install github.com/rakyll/hey@latest + +# Test search endpoint under load +hey -n 1000 -c 50 -H "Authorization: token $TOKEN" \ + "http://localhost:3000/api/v2/repos/test-org/test-repo/wiki/search?q=test" +``` + +### Expected Performance +- Search: < 500ms for wikis with < 100 pages +- List pages: < 200ms +- Get single page: < 100ms +- Graph generation: < 1s for wikis with < 100 pages + +--- + +## 6. Database Migration Testing + +### Test Migration Rollback + +```bash +# Backup before testing +cp gitea.db gitea.db.backup + +# Run migrations +./gitea migrate + +# Verify tables created +sqlite3 gitea.db ".tables" | grep -E "(wiki_index|pages_|org_pinned)" + +# Check table structure +sqlite3 gitea.db ".schema wiki_index" +sqlite3 gitea.db ".schema pages_config" +sqlite3 gitea.db ".schema org_pinned_repo" +``` + +### Verify Data Integrity + +```sql +-- Check no orphaned records +SELECT COUNT(*) FROM wiki_index WHERE repo_id NOT IN (SELECT id FROM repository); +SELECT COUNT(*) FROM pages_config WHERE repo_id NOT IN (SELECT id FROM repository); +SELECT COUNT(*) FROM org_pinned_repo WHERE org_id NOT IN (SELECT id FROM user WHERE type=1); +``` + +--- + +## 7. Staging Deployment + +### Recommended Staging Process + +1. **Clone Production Data** (sanitized) + ```bash + # Create sanitized copy of production DB + pg_dump production_db | psql staging_db + + # Remove sensitive data + UPDATE user SET passwd = 'disabled', salt = 'disabled' WHERE id > 1; + DELETE FROM access_token; + DELETE FROM oauth2_authorization_code; + ``` + +2. **Deploy to Staging** + ```bash + # Deploy v1.26.0 to staging + docker pull gitea/gitea:1.26.0 + docker-compose -f docker-compose.staging.yml up -d + ``` + +3. **Run Test Suite Against Staging** + ```bash + # Point tests at staging + export GITEA_URL=https://staging.gitea.example.com + export GITEA_TOKEN=staging-test-token + + # Run integration tests + go test -v ./tests/integration/... + ``` + +4. **Soak Test** (24-48 hours) + - Monitor error logs + - Check memory usage + - Verify no database locks + - Test with real (internal) users + +--- + +## 8. Rollback Plan + +### If Issues Found + +1. **Immediate Rollback** + ```bash + # Stop new version + docker-compose down + + # Restore previous version + docker pull gitea/gitea:1.25.3 + docker-compose up -d + ``` + +2. **Database Rollback** (if needed) + ```bash + # Restore from backup + pg_restore -d gitea gitea_backup.sql + + # Or for SQLite + cp gitea.db.backup gitea.db + ``` + +3. **New Tables Are Safe** + - Migration 326-328 only ADD tables + - No existing tables modified + - Rollback doesn't require table drops + - Old version simply ignores new tables + +--- + +## 9. Production Deployment Checklist + +### Pre-Deployment +- [ ] All automated tests passing +- [ ] Manual testing completed +- [ ] Staging deployment successful +- [ ] Database backup created +- [ ] Rollback procedure documented +- [ ] Maintenance window scheduled +- [ ] Users notified of downtime + +### Deployment +- [ ] Stop Gitea service +- [ ] Backup database +- [ ] Deploy new binary/container +- [ ] Run migrations +- [ ] Start Gitea service +- [ ] Verify health check endpoints +- [ ] Spot check critical features + +### Post-Deployment +- [ ] Monitor error logs for 1 hour +- [ ] Verify wiki search working +- [ ] Verify pages rendering +- [ ] Verify org profiles +- [ ] Check performance metrics +- [ ] Confirm with team leads + +--- + +## 10. Quick Smoke Test Script + +Save this as `smoke-test.sh`: + +```bash +#!/bin/bash +set -e + +BASE_URL="${GITEA_URL:-http://localhost:3000}" +TOKEN="${GITEA_TOKEN:-your-token}" +OWNER="test-org" +REPO="test-repo" + +echo "=== Gitea v1.26.0 Smoke Tests ===" + +# Health check +echo -n "Health check... " +curl -sf "$BASE_URL/api/v1/version" > /dev/null && echo "OK" || echo "FAIL" + +# Wiki V2 - List pages +echo -n "Wiki V2 - List pages... " +curl -sf -H "Authorization: token $TOKEN" \ + "$BASE_URL/api/v2/repos/$OWNER/$REPO/wiki/pages" > /dev/null && echo "OK" || echo "FAIL" + +# Wiki V2 - Search +echo -n "Wiki V2 - Search... " +curl -sf -H "Authorization: token $TOKEN" \ + "$BASE_URL/api/v2/repos/$OWNER/$REPO/wiki/search?q=test" > /dev/null && echo "OK" || echo "FAIL" + +# Wiki V2 - Stats +echo -n "Wiki V2 - Stats... " +curl -sf -H "Authorization: token $TOKEN" \ + "$BASE_URL/api/v2/repos/$OWNER/$REPO/wiki/stats" > /dev/null && echo "OK" || echo "FAIL" + +# Wiki V2 - Graph +echo -n "Wiki V2 - Graph... " +curl -sf -H "Authorization: token $TOKEN" \ + "$BASE_URL/api/v2/repos/$OWNER/$REPO/wiki/graph" > /dev/null && echo "OK" || echo "FAIL" + +# Org pinned repos +echo -n "Org pinned repos... " +curl -sf -H "Authorization: token $TOKEN" \ + "$BASE_URL/api/v1/orgs/$OWNER/pinned" > /dev/null && echo "OK" || echo "FAIL" + +# Pages config +echo -n "Pages config... " +curl -sf -H "Authorization: token $TOKEN" \ + "$BASE_URL/api/v1/repos/$OWNER/$REPO/pages" > /dev/null && echo "OK" || echo "FAIL" + +echo "=== Smoke Tests Complete ===" +``` + +Run with: +```bash +chmod +x smoke-test.sh +GITEA_URL=http://localhost:3000 GITEA_TOKEN=your-token ./smoke-test.sh +``` + +--- + +## Summary + +**Minimum Testing Before Production:** +1. Run automated test suite (`make test`) +2. Complete manual checklist for new features +3. Verify regression tests pass +4. Deploy to staging for 24+ hours +5. Run smoke tests after production deployment + +**The new features are isolated:** +- V2 Wiki API is separate from V1 (won't break existing integrations) +- New database tables don't modify existing schema +- Pages feature is opt-in per repository +- Org pinned repos don't affect existing org functionality