gitea/docs/testing-guide-v1.26.md

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

# 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

# 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:

# /tmp/gitea-test/app.ini
[database]
DB_TYPE = sqlite3
PATH = /tmp/gitea-test/data/gitea.db

---

2. Automated Tests

Run Existing Test Suite

# 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

// 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

# 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

# Search wiki
curl -H "Authorization: token $TOKEN" "$BASE/search?q=installation"

Graph & Stats

# 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

# 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

# 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

-- 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)

   # 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

   # 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

   # 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

   # 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)

   # 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:

#!/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:

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