Metrics Dashboard

Metrics Dashboard — Wiki

The Metrics Dashboard shows execution progress for the whole test project and per test plan (optionally split by platform). It replaces the legacy 1.9.20 lib/results/metricsDashboard.php (ExtJS progress bars + Ext table) with a modern Dashio-styled page backed by a plain-PHP REST BFF.

Path: ASIDE menu → Results → Metrics Dashboard URL: gui/templates/results/metricsDashboard.html?tproject_id=<id> (loaded inside the main frame) BFF API: api/metrics/index.php — GET /meta/rights, GET /dashboard?show_only_active=0|1[&tproject_id=] Rights: testplan_metrics OR testplan_execute (same OR-check as the legacy checkRights())

---

Table of Contents

1. Screen Layout
2. Project Progress
3. Test Plan Progress Table
4. Filters and Interactions
5. i18n
6. Permission Path and Empty State
7. BFF API Reference
8. Legacy Bugs Fixed
9. Files

---

1. Screen Layout

Section	Description
Header	Teal Dashio header "Metrics Dashboard — execution progress overview" with locale switcher
Toolbar	Dark bar: Show only active test plans checkbox + Public link toggle
Test Project Progress	Colored progress bars, one per execution status + overall executed
Test Plan Progress	DataTable: one row per test plan × platform with status qty/% columns and a progress mini-bar
Footer	"Generated on <timestamp>"

2. Project Progress

Progress bars mirror the legacy collectTestProjectMetrics(): overall executed plus one bar per status from $tlCfg->results['status_label_for_exec_ui'] (Not Run / Passed / Failed / Blocked). Each bar is annotated with [executed/active], where active = active test cases linked to the visible test plans. Percentages are rounded to $tlCfg->dashboard_precision, exactly like the legacy screen.

3. Test Plan Progress Table

One row per test plan (per platform when the plan uses platforms):

• Test Plan name (localized "n/a" platform column when the plan has no platforms)
• Active TCs (only plans with ACTIVE builds are considered, like legacy)
• Per status: quantity and percentage columns
• Progress % mini-bar; default sort: Progress % DESC (legacy setSortByColumnName(progress) DESC)

Data comes 1:1 from the same metrics managers used by legacy: tlTestPlanMetrics::getExecCountersByPlatformExecStatus() (platform branch) and getExecCountersByExecStatus() (no-platform branch), with getOnlyActiveTCVersions => true.

4. Filters and Interactions

• Show only active test plans — checkbox drives show_only_active, persisted in the session with the same tri-state semantics as legacy ($_SESSION['show_only_active']).
• Public link — toggles the legacy public deep link (lnl.php?type=metricsdashboard&apikey=<project api key>).
• DataTable search / sorting / paging work as on other modernized screens.

5. i18n

All strings come from the client-side TLi18n module — 21 new md.* keys added to ALL 10 locale bundles (en, de, es, fr, it, ja, pt, ro, ru, zh). Status column headers are generated dynamically from the server status set with localized labels.

6. Permission Path and Empty State

• Users lacking both rights see an error box ("You do not have the rights needed…"); the BFF answers 403.
• Projects without accessible test plans (or none with builds) show the legacy warning "No test plans available for the current test project!" instead of the tables.

7. BFF API Reference

Endpoint	Description
GET /meta/rights	{canView, showTestPlanStatus, precision}
GET /dashboard?show_only_active=&tproject_id=	Full payload: tproject_name, show_only_active, show_platforms, status_set, direct_link, warning, project_metrics[], testplans[], generated_on

Session-based auth (401 JSON otherwise); explicit ?tproject_id= wins over the session project, mirroring legacy R_PARAMS.

8. Legacy Bugs Fixed

• #559 — tlTestPlanMetrics::getExecCountersByExecStatus() always returned NULL (is_array($builds) check against a stdClass), so every plan WITHOUT platforms showed zeros on the legacy dashboard as well.
• #561 — PHP8 E_WARNINGs in buildExecStatusMatrix() (lines 1637/1639/1641): unguarded array access on NULL returned by get_full_path_verbose().

9. Files

• gui/templates/results/metricsDashboard.html — screen (HTML+CSS+JS)
• api/metrics/index.php — REST BFF
• lib/functions/common.php — aside link switched to the new screen
• lib/functions/tlTestPlanMetrics.class.php — bug fixes #559 / #561
• gui/templates/i18n/*.json — md.* keys

Test-plan grouping, grid toolbar and column filters (issue #1018, 2.0.1)

The Test Plan Progress grid was upgraded from a flat table to the full legacy Ext.Table grid chrome. See Issue-1018-MetricsDashboard-Grouping-Toolbar-Filters for the complete HOW.

• Rows are grouped by test plan with the legacy header Test Plan: <name> - Overall Progress: X% (N Item[s]); the grouped Test Plan column is hidden in the child rows (hideGroupedColumn), and a header click collapses/expands that group.
• Grouping is enabled only when platforms are shown (legacy parity).
• The DataTables RowGroup plugin is loaded from https://cdn.datatables.net/rowgroup/1.4.1/… — the versioned cdn.datatables.net/1.13.7/js/dataTables.rowGroup.js path 404s.
• The status qty columns are hidden by default (legacy 'hidden' => true) and are revealed by the new Show all columns button.
• New toolbar: Expand all groups, Collapse all groups, Show all columns, Reset Filters, Reset to default state, Refresh.
• A <tfoot> row carries one per-column filter input, and a platform list-filter <select> reproduces the legacy 'filter' => 'list', 'filterOptions' => $platforms.
• Sort parity: progress DESC, with the group ascending so groups stay contiguous.
• 13 new i18n keys in all 10 locale bundles.
• Regression suite 1018: 12/12 PASS, clean console, Event Viewer log_level IN (2,3) = 0.

Per-status breakdown behind show_test_plan_status (issue #1019, 2.0.1)

The test-plan cell now renders the legacy per-status breakdown when the config flag $tlCfg->metrics_dashboard->show_test_plan_status (config.inc.php:977, default false) is enabled. See Issue-1019-MetricsDashboard-PerStatus-Breakdown for the complete HOW.

• The cell shows Not Run: 4 [50%], Passed: 2 [25%], Failed: 1 [12.5%], Blocked: 1 [12.5%], Overall Progress: 50% — byte-identical to legacy (lib/results/metricsDashboard.php:50-72).
• Quantities and percentages come from the plan-level overall block with overall.active as the denominator, not from the per-platform row.
• The status list is read from the BFF status_set (array_keys(results.status_label_for_exec_ui)), so a custom exec status appears with no code change.
• /api/metrics/index.php/dashboard now also returns precision (config_get('dashboard_precision')); the builder defaults to 2 decimals.
• One new i18n key md.statusBreakdownItem in all 10 locale bundles; the existing md.status* / md.overallProgress keys are reused.
• With the flag off the collapsed form is unchanged (no sub-line).
• Regression suite 1019: 15/15 PASS, clean console, Event Viewer 0 new Error/Warning.

Bugfix #1698 — unknown executions.status code

A row in executions whose status code is outside config results.status_code used to be counted under an empty-string '' key (plus one E_WARNING Undefined array key per call), which the dashboard then counted as executed: progress could not be explained by any status column. Such rows are now counted on the explicit Unknown status — the BFF appends it to status_set only when a plan really has such rows, and the screen renders an Unknown bar + Unknown % column for it. One aggregated Event Viewer warning (activity=EXEC_STATUS) names the offending codes. Details, before / after measurements and the follow-ups: Bugfix-Issue-1698.