diff --git a/.github/chatmodes/debug.chatmode.md b/.github/chatmodes/debug.chatmode.md new file mode 100644 index 0000000000..cb02ceb03f --- /dev/null +++ b/.github/chatmodes/debug.chatmode.md @@ -0,0 +1,36 @@ +--- +description: 'Debug application to find and fix a bug' +model: GPT-5 (Preview) +tools: ['extensions', 'codebase', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'terminalSelection', 'terminalLastCommand', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'todos', 'runTests', 'runCommands', 'runTasks', 'editFiles', 'runNotebooks', 'search', 'new', 'Microsoft Docs', 'get_issue', 'get_issue_comments', 'get-library-docs', 'playwright', 'pylance mcp server'] +--- + +# Debug Mode Instructions + +You are in debug mode. Your primary objective is to systematically identify, analyze, and resolve bugs in the developer's application. Follow this structured debugging process: + +## Debugging process + +• **Gather context**: Read error messages/stack traces, examine recent changes, identify expected vs actual behavior. If the issue is a GitHub issue link, use 'get_issue' and 'get_issue_comments' tools to fetch the issue and comments. +• **Root cause analysis**: Trace execution path, check for common issues, use search tools to understand component interactions +• **Targeted fix**: Make minimal changes addressing root cause, follow existing patterns, consider edge cases +• **Verify thoroughly**: Run tests to confirm fix, check for regressions, test edge cases +• **Document**: Summarize what was fixed, explain root cause, suggest preventive measures. Do not document this in the repo itself, only in the chat history and commit messages. + +## Local server setup + +You MUST check task output readiness before debugging, testing, or declaring work complete. + +- Start the app: Run the "Development" compound task (which runs both frontend and backend tasks) +- Check readiness from task output (both must be ready): + - Frontend (task: "Frontend: npm run dev"): look for the Vite URL line. Either of these indicates ready: + - "Local: http://127.0.0.1:..." or "➜ Local: http://127.0.0.1:..." + - Backend (task: "Backend: quart run"): wait for Hypercorn to bind. Ready when you see: + - "INFO:hypercorn.error:Running on http://127.0.0.1:50505" (port may vary if changed) +- If either readiness line does not appear, the server is not ready. Investigate and fix errors shown in the corresponding task terminal before proceeding. +- Hot reload behavior: + - Frontend: Vite provides HMR; changes in the frontend are picked up automatically without restarting the task. + - Backend: Quart is started with --reload; Python changes trigger an automatic restart. + - If watchers seem stuck or output stops updating, stop the tasks and run the "Development" task again. +- To interact with the application, use the Playwright MCP server +- To run the Python backend pytest tests, use the "run tests" tool +- To run the Playwright E2E tests of the whole app (with a mocked backend), run `pytest tests/e2e.py --tracing=retain-on-failure`. diff --git a/.vscode/tasks.json b/.vscode/tasks.json index d4fdd8a2fe..f08aeb5cff 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -15,6 +15,74 @@ "cwd": "${workspaceFolder}/app" }, "problemMatcher": [] + }, + { + "label": "Development", + "dependsOn": [ + "Frontend: npm run dev", + "Backend: quart run" + ], + "group": { + "kind": "build", + "isDefault": true + } + }, + { + "label": "Frontend: npm run dev", + "type": "npm", + "script": "dev", + "isBackground": true, + "options": { + "cwd": "${workspaceFolder}/app/frontend" + }, + "presentation": { + "reveal": "always", + "group": "buildWatchers", + "panel": "dedicated", + "clear": false + }, + "problemMatcher": { + "pattern": { + "regexp": "" + }, + "background": { + "activeOnStart": true, + "beginsPattern": ".*VITE v.*", + "endsPattern": ".*(?:➜\\s*)?Local:\\s+https?://.*" + } + } + }, + { + "label": "Backend: quart run", + "type": "shell", + "command": "${workspaceFolder}/.venv/bin/python", + "windows": { + "command": "${workspaceFolder}\\.venv\\Scripts\\python.exe" + }, + "args": ["-m", "quart", "run", "--reload", "-p", "50505"], + "options": { + "cwd": "${workspaceFolder}/app/backend", + "env": { + "QUART_APP": "main:app", + "QUART_ENV": "development", + "QUART_DEBUG": "0", + "LOADING_MODE_FOR_AZD_ENV_VARS": "override" + } + }, + "isBackground": true, + "presentation": { + "reveal": "always", + "group": "buildWatchers", + "panel": "dedicated" + }, + "problemMatcher": { + "pattern": { "regexp": "" }, + "background": { + "activeOnStart": true, + "beginsPattern": ".*Serving Quart app.*", + "endsPattern": ".*hypercorn.*Running on http://.*" + } + } } ] } diff --git a/docs/localdev.md b/docs/localdev.md index b72199c029..35c40dc045 100644 --- a/docs/localdev.md +++ b/docs/localdev.md @@ -4,6 +4,8 @@ After deploying the app to Azure, you may want to continue development locally. * [Running development server from the command line](#running-development-server-from-the-command-line) * [Hot reloading frontend and backend files](#hot-reloading-frontend-and-backend-files) +* [Using VS Code "Development" task](#using-vs-code-development-task) +* [Using Copilot Chat Debug Mode](#using-copilot-chat-debug-mode) * [Using VS Code "Run and Debug"](#using-vs-code-run-and-debug) * [Using a local OpenAI-compatible API](#using-a-local-openai-compatible-api) * [Using Ollama server](#using-ollama-server) @@ -64,6 +66,56 @@ Navigate to the URL shown in the terminal (in this case, `http://localhost:5173/ Then, whenever you make changes to frontend files, the changes will be automatically reloaded, without any browser refresh needed. +Alternatively, you can start both servers with hot reloading by using the VS Code "Development" task. See [Using VS Code "Development" task](#using-vs-code-development-task). + +## Using VS Code "Development" task + +If you prefer VS Code tasks for hot reloading both servers at once, use the "Development" task defined in `.vscode/tasks.json`. + +How to run it: + +* Run Build Task (Shift+Cmd+B) to start the default build task, which is "Development". +* Or open the Command Palette (Shift+Cmd+P) and run: "Tasks: Run Task" -> "Development". + +What it does: + +* Starts two background tasks in dedicated panels: + * "Frontend: npm run dev" from `app/frontend` (Vite HMR for instant frontend updates) + * "Backend: quart run" from `app/backend` (Quart with `--reload` for backend auto-restarts) + +Readiness indicators: + +* Frontend is ready when Vite prints a Local URL, for example: `Local: http://localhost:5173/`. +* Backend is ready when Hypercorn reports: `Running on http://127.0.0.1:50505` (port may vary). + +Tips: + +* To stop both, run: "Tasks: Terminate Task" and pick the running tasks. +* If watchers stall, terminate and run "Development" again. +* Frontend changes apply via HMR; backend Python changes auto-reload. No manual restart needed. + +## Using Copilot Chat Debug Mode + +You can use GitHub Copilot Chat with a custom "debug" mode to streamline troubleshooting in this repo. + +Prerequisites: + +* VS Code 1.101+ (custom chat modes are in preview) +* Access to GitHub Copilot and Copilot Chat +* Playwright MCP server and GitHub MCP server (optional) + +To learn more about the chat modes feature, read [VS Code docs for Chat modes](https://code.visualstudio.com/docs/copilot/chat/chat-modes). + +To use the debug mode: + +* Open the Chat view. +* Use the chat mode dropdown at the top of the Chat view to select the "debug" mode. +* Start chatting in that mode; the instructions and tools from the repo file will be applied automatically. +* The mode will use the tasks from .vscode/tasks.json to run the frontend and backend server, and should be able to read any errors in the output. +* The mode may also use tools from the Playwright MCP server and GitHub MCP server, if those servers are installed in your VS Code. + +Notably, this mode will not actually use a breakpoint-based debugger. Read on to learn how to use breakpoints while debugging the Python code. + ## Using VS Code "Run and Debug" This project includes configurations defined in `.vscode/launch.json` that allow you to run and debug the app directly from VS Code: