Add comprehensive visual testing infrastructure with automated screenshot generation and VSCode UI mockups

.github/workflows/visual-testing.yml

@@ -0,0 +1,47 @@
+name: Visual Testing
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+jobs:
+  visual-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js 18.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18.x
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Compile TypeScript
+      run: npm run compile
+
+    - name: Generate visual documentation
+      run: npm run generate-screenshots
+
+    - name: Upload visual documentation
+      uses: actions/upload-artifact@v4
+      with:
+        name: visual-documentation
+        path: screenshots/
+        retention-days: 30
+
+    - name: Display summary
+      run: |
+        echo "✅ Visual documentation generated successfully!"
+        echo ""
+        echo "Generated files:"
+        ls -lh screenshots/
+        echo ""
+        echo "📊 Download the 'visual-documentation' artifact to view the results."

Dockerfile.test

@@ -0,0 +1,38 @@
+FROM codercom/code-server:latest
+
+USER root
+
+# Install dependencies
+RUN apt-get update && apt-get install -y \
+    wget \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up workspace
+WORKDIR /home/coder/workspace
+
+# Copy test projects
+COPY test-projects /home/coder/test-projects
+
+# Copy extension files
+COPY package.json package-lock.json tsconfig.json ./
+COPY src ./src
+COPY out ./out
+
+# Install Node.js dependencies
+RUN npm install
+
+# Install the extension globally in code-server
+RUN mkdir -p /home/coder/.local/share/code-server/extensions
+
+# Set proper permissions
+RUN chown -R coder:coder /home/coder
+
+USER coder
+
+# Expose code-server port
+EXPOSE 8080
+
+# Start code-server
+CMD ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "none", "/home/coder/test-projects/project-alpha"]

README.md

@@ -54,11 +54,14 @@ The extension includes comprehensive testing with GitHub CI integration:
 - `npm run test-unit` - Run unit tests (fast, no VSCode dependency)
 - `npm run test-all` - Run all unit tests with summary
 - `npm test` - Run integration tests (requires VSCode environment)
+- `npm run generate-screenshots` - Generate visual documentation with avatar previews
+- `npm run generate-vscode-ui` - Generate VSCode UI mockups showing extension in editor
 
 ### Test Structure
 
 - **Unit Tests** (`src/test/unit/`): Test core avatar generation logic without VSCode dependencies
 - **Integration Tests** (`src/test/integration/`): Test extension functionality within VSCode environment
+- **Visual Tests** (`scripts/generate-screenshots.js`): Generate visual documentation showing avatar output for test projects
 
 ### Continuous Integration
 
@@ -67,8 +70,37 @@ The project uses GitHub Actions for automated testing:
 - Unit tests validate core functionality
 - TypeScript compilation is verified
 - Extension packaging is tested
+- Visual documentation is generated automatically
 - Artifacts are uploaded for releases
 
+### Visual Testing
+
+The extension includes automated visual testing that generates screenshots and HTML previews:
+
+**Avatar Generation:**
+```bash
+npm run generate-screenshots
+```
+
+This creates interactive HTML pages in the `screenshots/` directory showing:
+- Avatar generation for multiple test projects
+- Light and dark theme variations
+- Multiple size demonstrations
+- Side-by-side comparisons
+
+**VSCode UI Mockups:**
+```bash
+npm run generate-vscode-ui
+```
+
+This creates realistic VSCode UI mockups in `screenshots/vscode-ui/` showing:
+- Full VSCode window with extension active
+- Status bar integration with project avatar
+- Webview panel displaying full avatar
+- Both light and dark VSCode themes
+
+See [Visual Testing Documentation](docs/VISUAL_TESTING.md) for details.
+
 ## AI-Powered Workflows
 
 This project includes AI-powered GitHub Actions workflows to enhance development:

docker-compose.test.yml

@@ -0,0 +1,30 @@
+version: '3.8'
+
+services:
+  vscode-project-alpha:
+    build:
+      context: .
+      dockerfile: Dockerfile.test
+    container_name: vscode-project-alpha
+    ports:
+      - "8081:8080"
+    volumes:
+      - ./test-projects/project-alpha:/home/coder/workspace
+      - ./out:/home/coder/extension/out
+    environment:
+      - PROJECT_NAME=project-alpha
+    command: ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "none", "--install-extension", "/home/coder/extension", "/home/coder/workspace"]
+
+  vscode-project-beta:
+    build:
+      context: .
+      dockerfile: Dockerfile.test
+    container_name: vscode-project-beta
+    ports:
+      - "8082:8080"
+    volumes:
+      - ./test-projects/project-beta:/home/coder/workspace
+      - ./out:/home/coder/extension/out
+    environment:
+      - PROJECT_NAME=project-beta
+    command: ["code-server", "--bind-addr", "0.0.0.0:8080", "--auth", "none", "--install-extension", "/home/coder/extension", "/home/coder/workspace"]

docs/DOCKER_TESTING.md

@@ -0,0 +1,97 @@
+# Docker-Based Visual Testing (Optional)
+
+This document describes the optional Docker-based testing approach for the Project Frimouss extension.
+
+## Overview
+
+While the `npm run generate-screenshots` command provides automated visual documentation, you can also test the extension in a real VSCode environment using Docker and code-server (VSCode in a browser).
+
+## Prerequisites
+
+- Docker installed and running
+- Docker Compose (optional, for multi-project setup)
+
+## Docker Setup
+
+### Dockerfile
+
+The `Dockerfile.test` provides a containerized VSCode environment:
+
+```dockerfile
+FROM codercom/code-server:latest
+# Sets up a VSCode instance with the extension pre-installed
+```
+
+### Docker Compose
+
+The `docker-compose.test.yml` orchestrates multiple VSCode instances:
+- One for `project-alpha` on port 8081
+- One for `project-beta` on port 8082
+
+## Running Docker Tests
+
+### Single Project
+
+```bash
+docker build -f Dockerfile.test -t vscode-frimouss-test .
+docker run -p 8080:8080 -v $(pwd)/test-projects/project-alpha:/home/coder/workspace vscode-frimouss-test
+```
+
+Then open http://localhost:8080 in your browser.
+
+### Multiple Projects
+
+```bash
+docker-compose -f docker-compose.test.yml up
+```
+
+This starts both test projects:
+- project-alpha: http://localhost:8081
+- project-beta: http://localhost:8082
+
+## Manual Testing Checklist
+
+When testing in the Docker environment:
+
+- [ ] Extension appears in the Extensions sidebar
+- [ ] Status bar shows project avatar icon
+- [ ] Status bar shows correct project name
+- [ ] Clicking status bar item opens avatar panel
+- [ ] Avatar panel displays full-size avatar
+- [ ] Avatar matches the project name
+- [ ] "Show Project Avatar" command works
+- [ ] "Refresh Project Avatar" command works
+- [ ] Avatar changes when switching between light/dark themes
+
+## Taking Screenshots
+
+1. Open the browser DevTools (F12)
+2. Use the device toolbar to set a consistent viewport
+3. Use browser screenshot tools or extensions
+4. Save screenshots to the `screenshots/` directory
+
+## Limitations
+
+- Docker-based testing requires network access to download code-server
+- Extension installation in code-server may require manual steps
+- May not perfectly replicate desktop VSCode behavior
+
+## Alternative: Automated Screenshot Generation
+
+For most use cases, the automated screenshot generation is recommended:
+
+```bash
+npm run generate-screenshots
+```
+
+This approach:
+- ✅ Doesn't require Docker
+- ✅ Runs in CI/CD environments
+- ✅ Generates consistent output
+- ✅ Creates interactive HTML previews
+- ✅ Tests both themes automatically
+
+## See Also
+
+- [Visual Testing Documentation](VISUAL_TESTING.md)
+- [code-server Documentation](https://github.com/coder/code-server)