nihantra-patel/testcase_manager

1. Top-level shape

- This repository is a Frappe app with a separate Vue 3 single-page frontend under frontend/.

- The backend serves the app at /testcase_manager, and the built frontend is copied into testcase_manager/www/testcase_manager.html plus testcase_manager/public/frontend/ during build.

2. Main domain objects

- The persistent model is centered on three DocTypes:

- Testcase: one discovered test method/spec.

- Testcase Run: one execution record, including status, timing, output, and traceback.

- Testcase Log: summary counts for a run, used for history/listing.

- These are the key persistence boundaries for the whole system.

3. Discovery subsystem

- testcase_manager/testcase_manager/discovery.py performs AST-based discovery of Python tests (test_*.py) across installed apps without importing them.

- ui_discovery.py separately discovers Cypress/UI specs using the app’s test file conventions.

- Discovery is automatically refreshed by hooks after migrations and on a daily scheduler run.

4. API boundary

- api.py exposes the whitelisted server endpoints consumed by the SPA.

- queries.py provides read-side listing/filtering queries for the UI.

- The frontend talks to these endpoints through frontend/src/api.js.

5. Python test execution path

- executor.py runs selected Python tests, typically in-process, and coordinates inline vs background execution depending on scope.

- It is the core execution engine for method/file/doctype/app/batch runs.

- Run lifecycle is managed so results can be persisted after completion.

6. UI/Cypress execution path

- ui_executor.py runs UI tests via bench run-ui-tests in a background job.

- This path is separate from Python execution because it is slower, headless-browser-based, and always run asynchronously.

- It streams output back just like Python runs, so the frontend treats both execution types similarly.

7. Realtime console and run lifecycle

- Execution output is published through Frappe realtime events, especially for live console updates.

- The frontend’s socket.js, useTestRunner.js, and Console.vue form the live subscription/display layer.

- The UI can stop queued or running jobs, and partial output is preserved in the saved run record.

8. Frontend structure

- The SPA is organized around views in frontend/src/pages/:

- RunnerView: discover/filter/select/run tests.

- HistoryView: browse past runs.

- RunDetailView: inspect one saved run.

- ProfilerView: profile document actions.

- router.js handles history-mode navigation inside the single app, while App.vue is the shell.

9. Test-impact analysis

- impact.py statically analyzes the app’s git diff to infer affected tests without running them.

- It uses import-graph relationships plus DocType links to select candidate tests.

- This is an analysis-only subsystem; it feeds the runner with a narrowed batch selection.

10. Document profiling subsystem

- profiling.py profiles a single document’s submit or cancel using cProfile.

- The operation runs inside a database savepoint and is rolled back, so hooks execute and timings are real, but nothing persists.

- This is a distinct non-persistent execution path from test runs.

11. Routing, hosting, and platform hooks

- hooks.py wires the app into Frappe routing, scheduler events, and log-retention behavior.

- website_route_rules maps SPA routes under /testcase_manager/... to the single HTML entrypoint.

- default_log_clearing_doctypes controls retention for run/log records.

12. Build and deployment boundary

- The frontend is built with Vite and packaged into the Frappe app during bench build.

- The root package.json and frontend/package.json split workspace/build concerns from the app runtime.

- GitHub Actions run backend tests, frontend build/lint checks, and separate UI test jobs, but these are CI concerns rather than runtime dependencies.

13. Architecture summary for a diagram

- A good diagram should show:

- Browser SPA → Frappe whitelisted APIs → discovery/execution/profiling services.

- Discovery populating the Testcase table.

- Execution creating/updating Testcase Run and Testcase Log records.

- Realtime events streaming back to the console over websockets.

- Scheduler/migration hooks keeping discovered tests in sync over time.