myAi/docs/skills/myai-smoke-test/SKILL.md

name, description, compatibility

name	description	compatibility
myai-smoke-test	Run a smoke test of the myAi CV Matcher application locally. Starts Docker Compose, uploads a CV, submits a job description, verifies CV analysis results display, and confirms the match email was sent. Use this skill whenever you need to validate that the core CV matching workflow is functioning correctly after code changes.	Requires Docker, Docker Compose, Chrome/Chromium, Python 3.8+, Selenium WebDriver

myAi Smoke Test Skill

Purpose

This skill automates a minimal end-to-end test of the myAi CV Matcher application running locally. It verifies:

1. Application starts and health check passes
2. CV upload and parsing works
3. Job description input and matching is triggered
4. CV analysis results display (score, strengths, gaps, evidence)
5. Match email is sent to the configured recipient

Use this after significant code changes to ensure the core workflow remains functional.

Prerequisites

• Docker & Docker Compose installed and running
• Chrome or Chromium browser installed (chromedriver auto-downloads via Selenium)
• Python 3.8+ with pip
• CV.pdf file in the project root (C:\Apps\easySoft\AI\myAi\CV.pdf)
• The myAi solution source code locally available
• Port 5140 available (web app), 8080 (api), 8081 (rag-api), 8082 (cv-matcher-api), 5432 (database), 1025 (mailhog)

Workflow

1. Start Application (45-second timeout)

The script launches Docker Compose from the project root:

docker compose -f docker-compose/docker-compose.yml up --build -d

Then waits up to 45 seconds for the web application at http://localhost:5140 to become ready (HTTP 200 on root path).

Success criteria: GET / returns HTTP 200 Failure: Application does not respond within 45 seconds → test fails with "Application startup timeout"

2. Open Browser & Navigate

Opens Chrome (in headless or visible mode, configurable) and navigates to the home page.

3. Upload CV (Hardcoded CV.pdf)

Uploads the CV.pdf file from the project root to the CV file input on the home page.

Expected behavior:

• File input accepts the PDF
• JavaScript triggers the file change handler
• Filename displays in the UI (e.g., "CV.pdf selected")

4. Fill Job Description (Hardcoded)

Fills the job description input with:

Senior Full Stack Engineer - 5+ years experience with C# ASP.NET Core, 
React, and cloud deployment. Experience with CI/CD pipelines, Docker, 
and agile teams required.

Expected behavior:

• Textarea accepts input
• Text is visible in the field

5. Submit Form (Completes reCaptcha if needed)

Clicks the "Submit" button to trigger the CV match API call.

Behavior:

• If reCaptcha is required, the script waits for it to be marked data-sitekey complete
• Form submission triggers async postCv() function
• API call goes to /api/cv/match with CV file and job description
• Response includes matchScore, strengths, gaps, evidence

6. Verify Results Display (30-second timeout)

Waits for results to appear on the page:

• Checks for .match-result container visibility
• Verifies match score badge displays (0-100%)
• Checks for strengths list (ul.strengths with li items)
• Checks for gaps list (ul.gaps with li items)
• Checks for evidence section (div.evidence with bullets)

Success criteria: All result elements present and visible within 30 seconds Failure: Results do not display → test fails with "Results did not display within timeout"

7. Verify Email Sent (Log Check)

Checks Docker container logs for email delivery confirmation:

• Inspects email-api container logs
• Searches for "Message sent" confirmation message
• Verifies the recipient includes the job candidate email

Success criteria: Log contains email send confirmation Failure: No email confirmation found → test fails with "Email was not sent"

8. Report Results

Reports one of:

• All passed: "✓ Smoke test passed. CV uploaded, matched (score: X%), results displayed, email sent."
• Partial failure: Details which step failed (e.g., "✗ Results did not display within timeout")
• Critical failure: "✗ Application failed to start" or "✗ File upload failed"

Hardcoded Values

These are built into the skill and do not require environment variables:

Value	Usage
CV.pdf (from root)	CV file upload
Senior Full Stack Engineer... (job desc)	Job matching criteria
http://localhost:5140	Web app home
45 seconds	App startup timeout
30 seconds	Results display timeout

Environment Variables (Optional)

Variable	Default	Purpose
HEADLESS_CHROME	true	Run Chrome in headless mode (no visible window)
DOCKER_COMPOSE_FILE	docker-compose/docker-compose.yml	Path to docker-compose.yml relative to project root
APP_PORT	5140	Port the web app runs on
APP_STARTUP_TIMEOUT	45	Seconds to wait for app health check
RESULTS_DISPLAY_TIMEOUT	30	Seconds to wait for results to appear
PROJECT_ROOT	Current directory	Root of myAi solution

Output

On success:

✓ Smoke test passed. CV uploaded, matched (score: 87%), results displayed, email sent.

On failure:

✗ Application failed to start (timeout after 45 seconds)
[Details of failed step]

Troubleshooting

"Application startup timeout"

• Verify Docker Compose is running: docker ps
• Check logs: docker logs myai-web-1
• Ensure port 5140 is not in use: netstat -an | grep 5140 (Windows) or lsof -i :5140 (Mac/Linux)

"File upload failed"

• Verify CV.pdf exists in project root
• Check file permissions (readable by your user)
• Ensure the file input element exists in the form

"Results did not display"

• Check browser console for JavaScript errors: docker logs myai-web-1
• Verify the /api/cv/match endpoint is responding: manually test with Postman
• Check cv-matcher-api logs: docker logs myai-cv-matcher-api-1

"Email was not sent"

• Verify email-api container is running: docker ps | grep email-api
• Check email-api logs: docker logs myai-email-api-1
• If using MailHog for local testing, verify it's accessible: http://localhost:1025

Chrome/Chromedriver issues

• Selenium automatically downloads chromedriver on first run
• If Chrome is not in PATH, install from https://chromedriver.chromium.org/
• Verify Chrome version matches chromedriver version

Running the Skill

python scripts/run_smoke_test.py

Or from within Claude:

• Trigger the skill with: "Run the myAi smoke test"
• Or: "Execute a smoke test of the CV matching workflow"

Implementation Notes

• Uses Selenium WebDriver with Chrome (auto-downloaded by webdriver-manager)
• Handles async JavaScript (waits for API response before checking results)
• Logs all steps to console with timestamps
• Automatically stops Docker Compose containers on test completion (can be disabled with KEEP_CONTAINERS=true)
• Tests are idempotent — can run multiple times without side effects