Bernard Siebens
e169d83311
Adds a run skill that starts the Django dev server, creates a test superuser, logs in via /admin/login/, and screenshots any page. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
---
|
|
name: run-teamforge
|
|
description: Build, run, and drive TeamForge. Use when asked to start TeamForge, run its tests, take a screenshot of its UI, verify a feature works, or interact with the running app.
|
|
---
|
|
|
|
TeamForge is a Django 6 club-management web app (members + teams). Drive it via `.claude/skills/run-teamforge/driver.mjs` under Playwright. The driver starts the dev server, creates a test superuser, logs in via `/admin/login/`, and screenshots any page.
|
|
|
|
All paths below are relative to the repo root (`/Users/bernard/Code/PycharmProjects/TeamForge/`).
|
|
|
|
## Prerequisites
|
|
|
|
Python (≥3.12) and `uv` must be present. Node.js (≥18) is required for the Playwright driver.
|
|
|
|
```bash
|
|
uv sync # install Python deps
|
|
npm install playwright # install Playwright (one-time, at repo root)
|
|
npx playwright install chromium # download Chromium browser (one-time, ~90 MB)
|
|
```
|
|
|
|
The app connects to a PostgreSQL database. Connection is in `.env`:
|
|
|
|
```
|
|
DJANGO_DATABASE_URL=postgres://...
|
|
DJANGO_DEBUG=True
|
|
```
|
|
|
|
If the database isn't reachable, the server still boots but all page requests fail with 500. The `.env` file must exist; there is no fallback to SQLite in production mode.
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
uv sync
|
|
uv run python manage.py migrate # apply migrations (idempotent)
|
|
```
|
|
|
|
## Run (agent path)
|
|
|
|
The driver handles everything — server startup, test-user creation, login, and screenshots.
|
|
|
|
```bash
|
|
# Smoke test: starts server, screenshots members + configuration pages
|
|
node .claude/skills/run-teamforge/driver.mjs smoke
|
|
|
|
# Screenshot any page (path or full URL)
|
|
node .claude/skills/run-teamforge/driver.mjs screenshot /backend/members/
|
|
node .claude/skills/run-teamforge/driver.mjs screenshot /backend/configuration
|
|
|
|
# Stop the background server
|
|
node .claude/skills/run-teamforge/driver.mjs stop
|
|
```
|
|
|
|
Screenshots land in `/tmp/teamforge-shots/<name>.png`. Server log → `/tmp/teamforge-server.log`.
|
|
|
|
Auth is via a local `skilltest` superuser (password: `skilltest123!`) which the driver creates automatically on first run. The driver logs in through `/admin/login/` — the app does not register `django.contrib.auth` URLs, so `/accounts/login/` returns 404.
|
|
|
|
## Run (human path)
|
|
|
|
```bash
|
|
uv run python manage.py runserver # → http://localhost:8000
|
|
python manage.py tailwind start # separate terminal — required for CSS
|
|
```
|
|
|
|
Log in at `/admin/login/` or create a superuser with `uv run python manage.py createsuperuser`.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
uv run python manage.py test # → 43 tests, all pass
|
|
```
|
|
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- **`/accounts/login/` returns 404** — the URL conf (`TeamForge/urls.py`) only has `backend/` and `admin/`. The `@login_required` decorator redirects there by default, but `django.contrib.auth.urls` is not included. Always log in via `/admin/login/`. The session cookie then works for all `/backend/` views.
|
|
|
|
- **`avatar` templatetag crashes on empty names** — `theme/templatetags/avatar.py:41` does `first_name[0]` which raises `IndexError: string index out of range` when either name field is blank. Every Django User used as a logged-in session must have `first_name` and `last_name` set. The driver sets them on the test user automatically.
|
|
|
|
- **`/backend/` dashboard is a placeholder** — `templates/backend/index.html` contains only "TEST FILE". This is expected during development; the real UI lives at `/backend/members/` and `/backend/configuration`.
|
|
|
|
- **Tailwind CSS not served in dev** — running `manage.py runserver` without `manage.py tailwind start` in a second terminal means pages render with no styles. The Playwright driver screenshots may look unstyled when Tailwind isn't running. For visual verification, start `tailwind start` first (or accept the unstyled capture).
|
|
|
|
- **PostgreSQL required** — `DJANGO_DATABASE_URL` in `.env` points to a remote PostgreSQL instance at `192.168.1.100`. If that host isn't reachable, every request returns 500. There is no in-repo SQLite fallback for normal runs; the test suite creates a separate test DB automatically.
|
|
|
|
- **`npm install playwright` must run at repo root** — the driver imports `playwright` via Node's resolution from `node_modules/` at the repo root. Running it from another directory will cause `ERR_MODULE_NOT_FOUND`.
|
|
|
|
## Troubleshooting
|
|
|
|
- **`Cannot find package 'playwright'`**: run `npm install playwright` at the repo root, then retry.
|
|
- **`Server did not start within 20s`**: check `/tmp/teamforge-server.log`. Most common cause: PostgreSQL unreachable (connection refused or timeout).
|
|
- **500 on every page after login**: the logged-in user has no `first_name`/`last_name` — the avatar templatetag crashes on the base template. Fix: set names on the user via `uv run python manage.py shell -c "from django.contrib.auth.models import User; u=User.objects.get(username='skilltest'); u.first_name='Skill'; u.last_name='Test'; u.save()"`.
|
|
- **`page.waitForURL` timeout on login**: admin login redirect failed — wrong password or user doesn't exist. The driver's `ensureTestUser()` recreates the user each run; if it fails, check that `manage.py shell` works at all.
|