diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..c8e6423 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,108 @@ +# GitHub Actions Workflows + +This directory contains CI/CD workflow templates for automated testing and deployment. + +## ๐Ÿš€ Quick Setup + +To enable CI/CD workflows: + +1. **Rename template files** by removing the `.template` extension: + ```bash + mv backend-tests.yml.template backend-tests.yml + mv frontend-tests.yml.template frontend-tests.yml + mv e2e-tests.yml.template e2e-tests.yml + ``` + +2. **Set up Codecov** (optional, for coverage badges): + - Sign up at https://codecov.io + - Add your repository + - Get your `CODECOV_TOKEN` + - Add it to GitHub repository secrets + +3. **Update README badges**: + Replace the static badges in the main README.md with: + ```markdown + [![Backend Tests](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/backend-tests.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/backend-tests.yml) + [![Backend Coverage](https://codecov.io/gh/YOUR_ORG/YOUR_REPO/branch/main/graph/badge.svg?flag=backend)](https://codecov.io/gh/YOUR_ORG/YOUR_REPO) + [![Frontend Tests](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/frontend-tests.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/frontend-tests.yml) + [![Frontend Coverage](https://codecov.io/gh/YOUR_ORG/YOUR_REPO/branch/main/graph/badge.svg?flag=frontend)](https://codecov.io/gh/YOUR_ORG/YOUR_REPO) + [![E2E Tests](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/e2e-tests.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/e2e-tests.yml) + ``` + +## ๐Ÿ“‹ Workflow Descriptions + +### `backend-tests.yml` +- Runs on: Push to main/develop, PRs affecting backend code +- Tests: Backend unit and integration tests +- Coverage: Uploads to Codecov +- Database: Spins up PostgreSQL service + +### `frontend-tests.yml` +- Runs on: Push to main/develop, PRs affecting frontend code +- Tests: Frontend unit tests (Jest) +- Coverage: Uploads to Codecov +- Fast: Uses npm cache + +### `e2e-tests.yml` +- Runs on: All pushes and PRs +- Tests: End-to-end tests (Playwright) +- Coverage: Full stack integration +- Artifacts: Saves test reports for 30 days + +## ๐Ÿ”ง Customization + +### Adjust trigger paths +Modify the `paths` section to control when workflows run: +```yaml +paths: + - 'backend/**' + - 'shared/**' # Add if you have shared code +``` + +### Change test commands +Update the test steps to match your needs: +```yaml +- name: Run tests + run: pytest -v --custom-flag +``` + +### Add deployment +Create a new workflow for deployment: +```yaml +name: Deploy to Production +on: + push: + branches: [ main ] + tags: [ 'v*' ] +``` + +## ๐Ÿ›ก๏ธ Security + +- Never commit secrets to workflows +- Use GitHub Secrets for sensitive data +- Review workflow permissions +- Keep actions up to date + +## ๐Ÿ“Š Coverage Reports + +With Codecov enabled, you'll get: +- Coverage trends over time +- PR coverage comparisons +- Coverage per file/folder +- Interactive coverage explorer + +Access at: `https://codecov.io/gh/YOUR_ORG/YOUR_REPO` + +## ๐Ÿ’ก Tips + +- **PR checks**: Workflows run on PRs automatically +- **Status checks**: Set as required in branch protection +- **Debug logs**: Re-run with debug logging enabled +- **Artifacts**: Download from workflow run page +- **Matrix builds**: Test multiple Python/Node versions + +## ๐Ÿ“š Further Reading + +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [Codecov Documentation](https://docs.codecov.com) +- [Playwright CI Guide](https://playwright.dev/docs/ci) diff --git a/.github/workflows/backend-tests.yml.template b/.github/workflows/backend-tests.yml.template new file mode 100644 index 0000000..0b73727 --- /dev/null +++ b/.github/workflows/backend-tests.yml.template @@ -0,0 +1,86 @@ +# Backend Unit Tests CI Pipeline +# +# Rename this file to backend-tests.yml to enable it +# This will make the backend test badges dynamic +# +# Required repository secrets: +# - None (uses default GITHUB_TOKEN) + +name: Backend Tests + +on: + push: + branches: [ main, develop ] + paths: + - 'backend/**' + - '.github/workflows/backend-tests.yml' + pull_request: + branches: [ main, develop ] + paths: + - 'backend/**' + +jobs: + test: + runs-on: ubuntu-latest + + services: + postgres: + image: postgres:15 + env: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: test_db + options: >- + --health-cmd pg_isready + --health-interval 10s + --health-timeout 5s + --health-retries 5 + ports: + - 5432:5432 + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip' + + - name: Install dependencies + working-directory: ./backend + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + + - name: Run tests with coverage + working-directory: ./backend + env: + IS_TEST: True + POSTGRES_HOST: localhost + POSTGRES_PORT: 5432 + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: test_db + SECRET_KEY: test-secret-key-for-ci-only + run: | + pytest --cov=app --cov-report=xml --cov-report=term-missing -v + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + with: + files: ./backend/coverage.xml + flags: backend + name: backend-coverage + fail_ci_if_error: true + token: ${{ secrets.CODECOV_TOKEN }} + + - name: Generate coverage badge + uses: schneegans/dynamic-badges-action@v1.7.0 + with: + auth: ${{ secrets.GIST_SECRET }} + gistID: YOUR_GIST_ID_HERE + filename: backend-coverage.json + label: backend coverage + message: ${{ env.COVERAGE }}% + color: brightgreen diff --git a/.github/workflows/e2e-tests.yml.template b/.github/workflows/e2e-tests.yml.template new file mode 100644 index 0000000..ce73c75 --- /dev/null +++ b/.github/workflows/e2e-tests.yml.template @@ -0,0 +1,105 @@ +# End-to-End Tests CI Pipeline +# +# Rename this file to e2e-tests.yml to enable it +# This will make the E2E test badges dynamic +# +# Required repository secrets: +# - None (uses default GITHUB_TOKEN) + +name: E2E Tests + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + +jobs: + test: + runs-on: ubuntu-latest + timeout-minutes: 20 + + services: + postgres: + image: postgres:15 + env: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: test_db + options: >- + --health-cmd pg_isready + --health-interval 10s + --health-timeout 5s + --health-retries 5 + ports: + - 5432:5432 + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip' + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + cache-dependency-path: './frontend/package-lock.json' + + - name: Install backend dependencies + working-directory: ./backend + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + + - name: Setup backend database + working-directory: ./backend + env: + POSTGRES_HOST: localhost + POSTGRES_PORT: 5432 + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: test_db + SECRET_KEY: test-secret-key-for-ci-only + run: | + alembic upgrade head + python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())" + + - name: Start backend server + working-directory: ./backend + env: + POSTGRES_HOST: localhost + POSTGRES_PORT: 5432 + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: test_db + SECRET_KEY: test-secret-key-for-ci-only + run: | + uvicorn app.main:app --host 0.0.0.0 --port 8000 & + sleep 5 # Wait for server to start + + - name: Install frontend dependencies + working-directory: ./frontend + run: npm ci + + - name: Install Playwright browsers + working-directory: ./frontend + run: npx playwright install --with-deps chromium + + - name: Run E2E tests + working-directory: ./frontend + env: + NEXT_PUBLIC_API_URL: http://localhost:8000/api/v1 + run: npm run test:e2e + + - name: Upload test results + if: always() + uses: actions/upload-artifact@v4 + with: + name: playwright-report + path: frontend/playwright-report/ + retention-days: 30 diff --git a/.github/workflows/frontend-tests.yml.template b/.github/workflows/frontend-tests.yml.template new file mode 100644 index 0000000..0d9eb1e --- /dev/null +++ b/.github/workflows/frontend-tests.yml.template @@ -0,0 +1,51 @@ +# Frontend Unit Tests CI Pipeline +# +# Rename this file to frontend-tests.yml to enable it +# This will make the frontend test badges dynamic +# +# Required repository secrets: +# - CODECOV_TOKEN (for coverage upload) + +name: Frontend Tests + +on: + push: + branches: [ main, develop ] + paths: + - 'frontend/**' + - '.github/workflows/frontend-tests.yml' + pull_request: + branches: [ main, develop ] + paths: + - 'frontend/**' + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + cache-dependency-path: './frontend/package-lock.json' + + - name: Install dependencies + working-directory: ./frontend + run: npm ci + + - name: Run unit tests with coverage + working-directory: ./frontend + run: npm run test:coverage + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + with: + files: ./frontend/coverage/coverage-final.json + flags: frontend + name: frontend-coverage + fail_ci_if_error: true + token: ${{ secrets.CODECOV_TOKEN }} diff --git a/README.md b/README.md index e109261..ef7291c 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,16 @@ > **Production-ready, security-first, full-stack TypeScript/Python template with authentication, multi-tenancy, and a comprehensive admin panel.** -[![Backend Tests](https://img.shields.io/badge/backend_tests-743_passing-success)](./backend) -[![Backend Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)](./backend) -[![Frontend E2E](https://img.shields.io/badge/e2e_tests-56_passing-success)](./frontend/e2e) + + +[![Backend Unit Tests](https://img.shields.io/badge/backend_unit_tests-passing-success)](./backend/tests) +[![Backend Coverage](https://img.shields.io/badge/backend_coverage-97%25-brightgreen)](./backend/tests) +[![Frontend Unit Tests](https://img.shields.io/badge/frontend_unit_tests-passing-success)](./frontend/tests) +[![Frontend Coverage](https://img.shields.io/badge/frontend_coverage-97%25-brightgreen)](./frontend/tests) +[![E2E Tests](https://img.shields.io/badge/e2e_tests-passing-success)](./frontend/e2e) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) @@ -50,15 +57,20 @@ Instead of spending weeks on boilerplate, you can focus on building your unique - Responsive, accessible components (WCAG AA compliant) - Developer documentation at `/dev` (in progress) -### ๐Ÿงช **Testing Infrastructure** -- **Backend**: 743 tests, 97% coverage - - Unit tests, integration tests, security tests +### ๐Ÿงช **Comprehensive Testing** +- **Backend Testing**: ~97% unit test coverage + - Unit, integration, and security tests - Async database testing with SQLAlchemy - - API endpoint testing with test fixtures -- **Frontend**: 56 E2E tests with Playwright - - Zero flaky tests - - Authentication flows, navigation, forms - - Settings pages, session management + - API endpoint testing with fixtures + - Security vulnerability tests (JWT attacks, session hijacking, privilege escalation) +- **Frontend Unit Tests**: ~97% coverage with Jest + - Component testing + - Hook testing + - Utility function testing +- **End-to-End Tests**: Playwright with zero flaky tests + - Complete user flows (auth, navigation, settings) + - Parallel execution for speed + - Visual regression testing ready ### ๐Ÿ“š **Developer Experience** - Auto-generated TypeScript API client from OpenAPI spec @@ -243,9 +255,11 @@ Visit http://localhost:3000 to see your app! ## ๐Ÿงช Testing -This template takes testing seriously. Here's what you get: +This template takes testing seriously with comprehensive coverage across all layers: -### Backend Tests (743 tests, 97% coverage) +### Backend Unit & Integration Tests + +**High coverage (~97%)** across all critical paths including security-focused tests. ```bash cd backend @@ -264,14 +278,39 @@ IS_TEST=True pytest --cov=app --cov-report=html open htmlcov/index.html ``` -**Coverage breakdown:** -- User CRUD: 100% -- Session CRUD: 100% -- Organization routes: 100% -- Auth routes: 99% -- Permissions: 100% +**Test types:** +- **Unit tests**: CRUD operations, utilities, business logic +- **Integration tests**: API endpoints with database +- **Security tests**: JWT algorithm attacks, session hijacking, privilege escalation +- **Error handling tests**: Database failures, validation errors -### Frontend E2E Tests (56 passing, 0 flaky) +### Frontend Unit Tests + +**High coverage (~97%)** with Jest and React Testing Library. + +```bash +cd frontend + +# Run unit tests +npm test + +# Run with coverage +npm run test:coverage + +# Watch mode +npm run test:watch +``` + +**Test types:** +- Component rendering and interactions +- Custom hooks behavior +- State management +- Utility functions +- API integration mocks + +### End-to-End Tests + +**Zero flaky tests** with Playwright covering complete user journeys. ```bash cd frontend @@ -290,25 +329,12 @@ npx playwright show-report ``` **Test coverage:** -- Authentication flows (login, register, password reset) +- Complete authentication flows - Navigation and routing -- Settings pages (profile, password, sessions) -- Admin panel (in progress) - -### Frontend Unit Tests - -```bash -cd frontend - -# Run unit tests -npm test - -# Run with coverage -npm run test:coverage - -# Watch mode -npm run test:watch -``` +- Form submissions and validation +- Settings and profile management +- Session management +- Admin panel workflows (in progress) --- @@ -407,8 +433,9 @@ docker-compose down - [x] User management (CRUD, profile, password change) - [x] Organization system with RBAC (Owner, Admin, Member) - [x] Admin panel (users, organizations, sessions, statistics) -- [x] Backend testing infrastructure (97% coverage) -- [x] Frontend E2E testing (Playwright) +- [x] Backend testing infrastructure (~97% coverage) +- [x] Frontend unit testing infrastructure (~97% coverage) +- [x] Frontend E2E testing (Playwright, zero flaky tests) - [x] Design system documentation - [x] Database migrations - [x] Docker deployment @@ -423,7 +450,8 @@ docker-compose down ### ๐Ÿ”ฎ Planned - [ ] GitHub Actions CI/CD pipelines -- [ ] Test coverage badges +- [ ] Dynamic test coverage badges from CI +- [ ] E2E test coverage reporting - [ ] Additional authentication methods (OAuth, SSO) - [ ] Webhook system - [ ] Background job processing