diff --git a/.github/skills/dev-workflow.md b/.github/skills/dev-workflow.md index f78916fa..60fa6001 100644 --- a/.github/skills/dev-workflow.md +++ b/.github/skills/dev-workflow.md @@ -21,7 +21,7 @@ This invokes `robotframework_dashboard/main.py:main()` directly and supports all ## Common Dev Invocations ```powershell -# Generate a dashboard from a single output.xml into robot_dashboard.html (default output) +# Generate a dashboard from a single output.xml (default output: robot_dashboard_.html) python -m robotframework_dashboard.main -o results\output-20251225-172034.xml # Generate from multiple output.xml files @@ -30,18 +30,20 @@ python -m robotframework_dashboard.main -o results\output-20251225-172034.xml re # Generate from a folder of output.xml files python -m robotframework_dashboard.main -f results -# Use a custom output HTML path -python -m robotframework_dashboard.main -o results\output-20251225-172034.xml -g my_dashboard.html +# Use a custom output HTML path (-n / --namedashboard, NOT -g) +python -m robotframework_dashboard.main -o results\output-20251225-172034.xml -n my_dashboard.html # Offline mode (no CDN, all dependencies embedded) python -m robotframework_dashboard.main -o results\output-20251225-172034.xml --offlinedependencies ``` +`-g` / `--generatedashboard` is a **boolean** flag (default `True`) — it does not take a filename. Use `-n` / `--namedashboard` for a custom output path. + ## Generated Output -- Default output file: `robot_dashboard.html` in the current working directory. +- Default output file: `robot_dashboard_.html` in the current working directory, unless `-n` is given. - The file is fully self-contained: all JS, CSS, and data are embedded — open it directly in a browser with no server needed. -- Re-running does **not** overwrite an existing database by default. To reset, delete the `.db` file (default: `robot_database.db`) before re-running, or specify a different `-d DATABASEPATH`. +- Default database file: `robot_results.db`. Re-running does **not** overwrite an existing database. To reset, delete the `.db` file before re-running, or specify a different `-d DATABASEPATH`. ## Inspecting JS/CSS Changes @@ -61,7 +63,31 @@ Template changes in `robotframework_dashboard/templates/dashboard.html` also req ```powershell # 1. Make changes to js/, css/, or templates/ # 2. Regenerate (delete old db if you want a clean state) -Remove-Item robot_database.db -ErrorAction SilentlyContinue -python -m robotframework_dashboard.main -o results\output-20251225-172034.xml +Remove-Item robot_results.db -ErrorAction SilentlyContinue +python -m robotframework_dashboard.main -o results\output-20251225-172034.xml -n robot_dashboard.html # 3. Open robot_dashboard.html in a browser ``` + +## Validating JS/CSS/Template Changes + +After any change to `robotframework_dashboard/js/`, `css/`, or `templates/dashboard.html`, **regenerate the HTML** to confirm the bundler/template still produce valid output — importing a module and checking it doesn't throw is not enough, since most bugs (rendering, layout, icon sizing, click handlers) only show up in the bundled, rendered output. + +The repo ships with output.xml fixtures under `tests/` that work as a ready-made dataset: + +```bash +# From the repo root (Git Bash / Linux / macOS) +python -m robotframework_dashboard.main -f tests -n robot_dashboard.html +``` + +```powershell +# Windows PowerShell +python -m robotframework_dashboard.main -f tests -n robot_dashboard.html +``` + +**Do not install or drive a browser (Playwright, Selenium, etc.) as part of this validation.** Regenerating the dashboard without errors, plus a careful read of the diff, is the AI agent's verification step. Actually opening `robot_dashboard.html` and exercising the feature in a browser (e.g. enabling "Customize Layout" to check edit-mode controls) is a manual step left to the developer — describe what to click and what to expect instead of trying to automate it. + +Clean up the generated `robot_dashboard.html` and `robot_results.db` once done if they aren't meant to be committed. + +### Gotcha: trailing backslashes in paths (Git Bash) + +In Git Bash on Windows, a Windows-style path with a trailing backslash (e.g. `-f .\tests\`) gets the backslash interpreted as escaping the following space — this silently merges the *next* argument (and its value) into the path, so e.g. `-f .\tests\ -n robot_dashboard.html` is parsed as a single `-f` value and `-n`/`robot_dashboard.html` are swallowed, silently falling back to defaults. Use a forward-slash path with no trailing slash instead: `-f tests`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..77950af1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,152 @@ +# robotframework-dashboard — Copilot Instructions + +This file gives AI agents and contributors the context needed to work effectively in this codebase. + +## How to Use the Skills Files + +Before starting work on any non-trivial task, read the relevant skill file from `.github/skills/`. Each file contains deep domain knowledge that avoids re-exploring the codebase from scratch. Use the table in the **Skills** section below to pick the right one(s). Read the skill file with a file-read tool before making any changes. + +--- + +## Commands + +Use the project scripts — do NOT invoke the underlying tools directly (the scripts set coverage paths, artifact dirs, and parallelism). `.bat` for Windows, `.sh` for Linux/macOS. + +| Task | Windows | Linux / macOS | +|---|---|---| +| JS unit tests | `scripts\javascript-tests.bat` | `bash scripts/javascript-tests.sh` | +| Python unit tests | `scripts\python-tests.bat` | `bash scripts/python-tests.sh` | +| Robot acceptance tests | `scripts\robot-tests.bat` | `bash scripts/robot-tests.sh` | +| Generate dashboard for testing | `python -m robotframework_dashboard.main -n robot_dashboard -f tests` | same | +| Docs build | `npm run docs:build` | `npm run docs:build` | +| Docs dev server | `npm run docs:dev` | `npm run docs:dev` | + +**Generate dashboard for testing** runs the package directly (no install) against the `tests/` output.xml fixtures, producing `robot_dashboard.html`. Use this to validate any JS/CSS/template/Python pipeline change — open the HTML to confirm rendering, layout, and click handlers. A clean import/syntax check is not sufficient; bundled-output bugs only surface here. + +--- + +## Project Purpose + +`robotframework-dashboard` is a Python CLI tool that reads Robot Framework `output.xml` execution results, stores them in a SQLite database, and generates a fully self-contained HTML dashboard with interactive charts, tables, and filters. No web server is required to view the output — a single `.html` file contains all data, JS, and CSS. + +--- + +## Core Pipeline: Python CLI → HTML Template → JavaScript + +The entire system is this three-stage pipeline: + +``` +1. PYTHON CLI + output.xml files + └─► OutputProcessor (robot.api ResultVisitor) + └─► SQLite database (runs / suites / tests / keywords tables) + +2. HTML TEMPLATE + database.get_data() + └─► DashboardGenerator + ├─► DependencyProcessor: merges all JS modules (topological sort) → inline