git/docker-swarm-termina
1
0
Fork 0
mirror of https://github.com/johndoe6345789/docker-swarm-termina.git synced 2026-04-24 13:45:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update CLAUDE.md with Docker/gh install instructions and accurate testing workflow

Browse Source 
Major improvements:
1. Added Prerequisites section with installation instructions for:
   - Docker (Ubuntu/Debian and macOS)
   - GitHub CLI (gh)
   - Verification commands for both

2. Fixed testing workflow to reflect reality:
   - Option A (RECOMMENDED): Local testing with e2e + mock backend
   - Option B: Full Docker build (CI-equivalent)
   - Option C: Minimum verification (fallback)
   - Removed misleading instructions about Docker being "preferred"

3. Added Mock Backend documentation:
   - Explains e2e/mock-backend.js
   - Auto-starts on port 5000
   - No manual setup needed
   - Mock credentials listed

4. Expanded Development Commands:
   - All common npm commands
   - Specific test running examples
   - E2E test debugging with UI mode

5. Added Troubleshooting section:
   - Playwright browser installation issues
   - Connection refused errors
   - Docker build failures
   - Finding test expectations

6. Added Summary workflow checklist:
   - Clear 7-step process
   - Matches actual testing requirements

This should prevent future issues where AI assistants:
- Don't know how to install Docker/gh
- Use wrong testing workflow
- Don't understand mock backend setup
- Commit without proper verification

https://claude.ai/code/session_01T57NPQfoRb2fS7ihdWkTxq
This commit is contained in:
Claude
2026-02-01 20:01:26 +00:00
parent 277ab3e328
commit ddb965bea9
1 changed files with 164 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
CLAUDE.md
View File

@@ -1,5 +1,59 @@
# AI Assistant Guidelines for Docker Swarm Terminal
## Prerequisites
Before working on this project, ensure you have:
- **Node.js 20+** - Required for frontend development
- **Docker** - Required for running CI-equivalent tests (optional but recommended)
- **GitHub CLI (gh)** - Required for creating pull requests
### Installing Docker
**Ubuntu/Debian:**
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect
```
**macOS:**
```bash
brew install --cask docker
# Or download Docker Desktop from https://www.docker.com/products/docker-desktop
```
**Verify installation:**
```bash
docker --version
docker ps
```
### Installing GitHub CLI
**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install gh
```
**macOS:**
```bash
brew install gh
```
**Verify installation:**
```bash
gh --version
gh auth status
```
**Authenticate:**
```bash
gh auth login
```
## Critical Testing Requirements
**NEVER commit code without verifying it works with the existing tests.**
@@ -30,14 +84,7 @@ When making changes to components or functionality:
3. **Verify tests pass** - You MUST verify tests before committing:
**Option A: Full Docker build (preferred - runs both unit + e2e tests):**
```bash
cd frontend && docker build -t frontend-test .
```
Note: The Dockerfile runs e2e tests at line 55, but allows them to skip if backend services aren't running. The e2e tests WILL run in CI and WILL show failures even if they don't block the build.
**Option B: Local testing without Docker:**
**Option A: Local testing with e2e (RECOMMENDED):**
```bash
cd frontend
@@ -50,16 +97,26 @@ When making changes to components or functionality:
# Step 3: Build the app (REQUIRED - must succeed)
npm run build
# Step 4: Run e2e tests (RECOMMENDED if you can start the app)
# Terminal 1: Start the frontend
npm run dev
# Terminal 2: Run e2e tests
# Step 4: Run e2e tests with mock backend (automatically starts servers)
npx playwright install chromium --with-deps
npm run test:e2e
```
**Option C: Minimum verification (if Docker/local e2e not available):**
**Note:** Playwright automatically starts:
- Mock backend server on port 5000 (`e2e/mock-backend.js`)
- Frontend dev server on port 3000 (`npm run dev`)
- Both servers shut down automatically when tests complete
**Option B: Full Docker build (CI-equivalent):**
```bash
cd frontend && docker build -t frontend-test .
```
**Warning:** The Dockerfile runs e2e tests at line 55 but allows them to skip
if backend services aren't running. In CI, e2e tests may show failures but
won't block the build. Always run Option A locally to catch issues early.
**Option C: Minimum verification (if e2e cannot run):**
```bash
cd frontend
npm ci # Install dependencies
@@ -105,19 +162,46 @@ When making changes to components or functionality:
## Development Commands
```bash
# Run all tests in Docker (CI environment)
docker build --target test .
# Install frontend dependencies
cd frontend && npm ci
# Run e2e tests locally (requires dependencies)
cd frontend && npm run test:e2e
# Run unit tests locally
# Run unit tests
cd frontend && npm test
# Run specific test file
# Run specific unit test file
cd frontend && npm test -- LoginForm
# Run unit tests with coverage
cd frontend && npm run test:coverage
# Build the frontend
cd frontend && npm run build
# Run e2e tests (auto-starts mock backend + dev server)
cd frontend && npm run test:e2e
# Run specific e2e test
cd frontend && npx playwright test login.spec.ts
# Run e2e tests with UI (for debugging)
cd frontend && npm run test:e2e:ui
# Build frontend Docker image (runs all tests)
cd frontend && docker build -t frontend-test .
```
## Mock Backend for E2E Tests
The project includes a mock backend (`frontend/e2e/mock-backend.js`) that:
- Runs on `http://localhost:5000`
- Provides mock API endpoints for login, containers, etc.
- Automatically starts when running `npm run test:e2e`
- No manual setup required
**Mock credentials:**
- Username: `admin`
- Password: `admin123`
## Project Structure
- `frontend/` - Next.js application
@@ -135,4 +219,63 @@ cd frontend && npm test -- LoginForm
3. Push to the designated branch only
4. Tests must pass in CI before merging
## Troubleshooting
### Playwright browser installation fails
If `npx playwright install` fails with network errors:
```bash
# Try manual download
curl -L -o /tmp/chrome.zip "https://cdn.playwright.dev/builds/cft/[VERSION]/linux64/chrome-linux64.zip"
mkdir -p ~/.cache/ms-playwright/chromium_headless_shell-[VERSION]
cd ~/.cache/ms-playwright/chromium_headless_shell-[VERSION]
unzip /tmp/chrome.zip
mv chrome-linux64 chrome-headless-shell-linux64
cd chrome-headless-shell-linux64 && cp chrome chrome-headless-shell
```
### E2E tests fail with "ERR_CONNECTION_REFUSED"
The mock backend or dev server isn't starting. Check:
```bash
# Make sure ports 3000 and 5000 are free
lsof -ti:3000 | xargs kill -9
lsof -ti:5000 | xargs kill -9
# Verify Playwright config is correct
cat frontend/playwright.config.ts | grep webServer
```
### Docker build fails
```bash
# Check Docker is running
docker ps
# Build with more verbose output
cd frontend && docker build --progress=plain -t frontend-test .
# Build specific stage only
cd frontend && docker build --target test -t frontend-unit-tests .
```
### Tests expect different text than component shows
**Always read the test files first before making changes!**
```bash
# Find what text the tests expect
grep -r "getByRole\|getByText\|getByLabel" frontend/e2e/
grep -r "getByRole\|getByText\|getByLabel" frontend/**/__tests__/
```
## Summary: Complete Workflow
1. ✅ **Read test files** to understand expectations
2. ✅ **Make changes** matching what tests expect
3. ✅ **Run unit tests**: `npm test` (must pass)
4. ✅ **Run build**: `npm run build` (must succeed)
5. ✅ **Run e2e tests**: `npm run test:e2e` (should pass)
6. ✅ **Commit** only after all tests pass
7. ✅ **Push** to designated branch
Remember: **Code that doesn't pass tests is broken code.** Always verify before committing.