Ryan Kegel
a8d7427a95
Some checks failed
Chore App Build, Test, and Push Docker Images / build-and-push (push) Failing after 1m44s
- Added E2E test setup in `auth_api.py` with `/e2e-seed` endpoint for database reset and test user creation. - Integrated Playwright for end-to-end testing in the frontend with necessary dependencies in `package.json` and `package-lock.json`. - Created Playwright configuration in `playwright.config.ts` to manage test execution and server setup. - Developed new skills for Playwright best practices, visual regression, smoke test generation, and self-healing tests. - Implemented new test cases for chore creation in `chores-create.smoke.spec.ts` and `chores-create.spec.ts`. - Added page object models for `ChildEditPage` and `LandingPage` to streamline test interactions. - Updated `.gitignore` to exclude Playwright reports and test results. - Enhanced documentation in `copilot-instructions.md` for testing and E2E setup.
65 lines
5.2 KiB
Markdown
65 lines
5.2 KiB
Markdown
# Reward Project: AI Coding Agent Instructions
|
|
|
|
## 🏗️ Architecture & Data Flow
|
|
|
|
- **Stack**: Flask (Python, backend) + Vue 3 (TypeScript, frontend) + TinyDB (JSON, thread-safe, see `db/`).
|
|
- **API**: RESTful endpoints in `api/`, grouped by entity (child, reward, task, user, image, etc). Each API file maps to a business domain.
|
|
- **Nginx Proxy**: Frontend nginx proxies `/api/*` to backend, stripping the `/api` prefix. Backend endpoints should NOT include `/api` in their route definitions. Example: Backend defines `@app.route('/user')`, frontend calls `/api/user`.
|
|
- **Models**: Maintain strict 1:1 mapping between Python `@dataclass`es (`backend/models/`) and TypeScript interfaces (`frontend/vue-app/src/common/models.ts`).
|
|
- **Database**: Use TinyDB with `from_dict()`/`to_dict()` for serialization. All logic should operate on model instances, not raw dicts.
|
|
- **Events**: Real-time updates via Server-Sent Events (SSE). Every mutation (add/edit/delete/trigger) must call `send_event_for_current_user` (see `backend/events/`).
|
|
- **Changes**: Do not use comments to replace code. All changes must be reflected in both backend and frontend files as needed.
|
|
- **Specs**: If specs have a checklist, all items must be completed and marked done.
|
|
|
|
## 🧩 Key Patterns & Conventions
|
|
|
|
- **Frontend Styling**: Use only `:root` CSS variables from `colors.css` for all colors, spacing, and tokens. Example: `--btn-primary`, `--list-item-bg-good`.
|
|
- **Scoped Styles**: All `.vue` files must use `<style scoped>`. Reference global variables for theme consistency.
|
|
- **API Error Handling**: Backend returns JSON with `error` and `code` (see `backend/api/error_codes.py`). Frontend extracts `{ msg, code }` using `parseErrorResponse(res)` from `api.ts`.
|
|
- **JWT Auth**: Tokens are stored in HttpOnly, Secure, SameSite=Strict cookies.
|
|
- **Code Style**:
|
|
1. Follow PEP 8 for Python, and standard TypeScript conventions.
|
|
2. Use type annotations everywhere in Python.
|
|
3. Place all imports at the top of the file.
|
|
4. Vue files should specifically place `<template>`, `<script>`, then `<style>` in that order. Make sure to put ts code in `<script>` only.
|
|
|
|
## 🚦 Frontend Logic & Event Bus
|
|
|
|
- **SSE Event Management**: Register listeners in `onMounted`, clean up in `onUnmounted`. Listen for events like `child_task_triggered`, `child_reward_request`, `task_modified`, etc. See `frontend/vue-app/src/common/backendEvents.ts` and `components/BackendEventsListener.vue`.
|
|
- **Layout Hierarchy**: Use `ParentLayout` for admin/management, `ChildLayout` for dashboard/focus views.
|
|
|
|
## ⚖️ Business Logic & Safeguards
|
|
|
|
- **Token Expiry**: Verification tokens expire in 4 hours; password reset tokens in 10 minutes.
|
|
- **Image Assets**: Models use `image_id` for storage; frontend resolves to `image_url` for rendering.
|
|
|
|
## 🛠️ Developer Workflows
|
|
|
|
- **Backend**: Run Flask with `python -m flask run --host=0.0.0.0 --port=5000` from the `backend/` directory. Main entry: `backend/main.py`.
|
|
- **Virtual Env**: Python is running from a virtual environment located at `backend/.venv/`.
|
|
- **Frontend**: From `frontend/vue-app/`, run `npm install` then `npm run dev`.
|
|
- **Tests**: Run backend tests with `pytest` in `backend/tests/`. Frontend component tests: `npm run test` in `frontend/vue-app/components/__tests__/`. E2E tests: `npx playwright test` from `frontend/vue-app/` — requires both servers running (use the `flask-backend` and `vue-frontend` skills).
|
|
- **E2E Setup**: Playwright config is at `frontend/vue-app/playwright.config.ts`. Tests live in `frontend/vue-app/tests/`. The `globalSetup` in `playwright.config.ts` seeds the database and logs in once; all tests receive a pre-authenticated session via `storageState` — do NOT navigate to `/auth/login` in tests. Import `E2E_EMAIL` and `E2E_PASSWORD` from `tests/global-setup.ts` rather than hardcoding credentials. The backend must be started with `DB_ENV=e2e DATA_ENV=e2e` (the `flask-backend` skill does this) so test data goes to `backend/test_data/` and never touches production data.
|
|
- **Debugging**: Use VS Code launch configs or run Flask/Vue dev servers directly. For SSE, use browser dev tools to inspect event streams.
|
|
|
|
## 📁 Key Files & Directories
|
|
|
|
- `backend/api/` — Flask API endpoints (one file per entity)
|
|
- `backend/models/` — Python dataclasses (business logic, serialization)
|
|
- `backend/db/` — TinyDB setup and helpers
|
|
- `backend/events/` — SSE event types, broadcaster, payloads
|
|
- `frontend/vue-app/` — Vue 3 frontend (see `src/common/`, `src/components/`, `src/layout/`) - Where tests are run from
|
|
- `frontend/vue-app/src/common/models.ts` — TypeScript interfaces (mirror Python models)
|
|
- `frontend/vue-app/src/common/api.ts` — API helpers, error parsing, validation
|
|
- `frontend/vue-app/src/common/backendEvents.ts` — SSE event types and handlers
|
|
|
|
## 🧠 Integration & Cross-Component Patterns
|
|
|
|
- **Every backend mutation must trigger an SSE event** for the current user.
|
|
- **Frontend state is event-driven**: always listen for and react to SSE events for real-time updates.
|
|
- **Model changes require updating both Python and TypeScript definitions** to maintain parity.
|
|
|
|
---
|
|
|
|
For any unclear or missing conventions, review the referenced files or ask for clarification. Keep this document concise and actionable for AI agents.
|