From f84948153b0019c315fe431eab6de7ee4921f638 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 31 Oct 2026 15:22:33 +0000 Subject: [PATCH] feat(app): add debug toggle for turn documents --- .../artifacts/ui/artifact_gallery_page.dart | 76 ++++++++++++++--- .../artifacts/ui/artifact_visit_list.dart | 85 +++++++++---------- .../ui/artifact_gallery_documents_test.dart | 43 ++++------ .../ui/run_detail_visit_sections_test.dart | 20 +++-- 4 files changed, 137 insertions(+), 87 deletions(-) diff --git a/app/lib/features/artifacts/ui/artifact_gallery_page.dart b/app/lib/features/artifacts/ui/artifact_gallery_page.dart index 35433231..51c127ca 100644 --- a/app/lib/features/artifacts/ui/artifact_gallery_page.dart +++ b/app/lib/features/artifacts/ui/artifact_gallery_page.dart @@ -89,6 +89,7 @@ class _ArtifactGalleryPageState extends State { late final List _groups = _groupsOf(widget.focusIndex); String? _selectedIdentity; String? _status; + bool _showTurnDocuments = false; List _groupsOf(int? focusIndex) { final allGroups = _withRepairDocuments(galleryGroups(widget.steps)); @@ -436,7 +437,7 @@ class _ArtifactGalleryPageState extends State { /// with many partial visits — or a focused visit at large text — scrolls with /// the artifacts instead of taking height from them. It is content-driven: /// one line per recorded fact, never clamped or shortened. - Widget _header(BuildContext context, String summary) { + Widget _header(BuildContext context, String summary, {Widget? action}) { final notes = _captureNotes(); final cupertino = usesCupertinoHost(context); final textStyle = cupertino @@ -456,10 +457,17 @@ class _ArtifactGalleryPageState extends State { crossAxisAlignment: CrossAxisAlignment.start, mainAxisSize: MainAxisSize.min, children: [ - Semantics( - container: true, - header: true, - child: Text(summary, style: headingStyle), + Row( + children: [ + Expanded( + child: Semantics( + container: true, + header: true, + child: Text(summary, style: headingStyle), + ), + ), + ?action, + ], ), for (final note in notes) Padding( @@ -476,38 +484,86 @@ class _ArtifactGalleryPageState extends State { ); } + Widget _debugToggle(BuildContext context) { + final showing = _showTurnDocuments; + final label = showing ? 'Hide turn documents' : 'Show turn documents'; + // Cupertino's bundled icon font has no bug glyph; retain the universally + // recognisable Material bug icon inside its native Cupertino button. + final icon = showing ? Icons.bug_report : Icons.bug_report_outlined; + void onPressed() => setState(() => _showTurnDocuments = !showing); + final button = usesCupertinoHost(context) + ? CupertinoButton( + key: const Key('artifact-debug-toggle'), + padding: EdgeInsets.zero, + onPressed: onPressed, + child: Icon(icon), + ) + : IconButton( + key: const Key('artifact-debug-toggle'), + isSelected: showing, + tooltip: label, + onPressed: onPressed, + icon: Icon(icon), + ); + final semanticButton = Semantics( + label: label, + button: true, + toggled: showing, + child: button, + ); + return usesCupertinoHost(context) + ? Tooltip(message: label, child: semanticButton) + : semanticButton; + } + @override Widget build(BuildContext context) { final groups = _groups; - final header = _header(context, _summary(groups)); + final visibleGroups = [ + for (final group in groups) + if (group.artifacts.isNotEmpty || + (_showTurnDocuments && group.documents.isNotEmpty)) + group, + ]; + final header = _header( + context, + _summary(groups), + action: widget.embedded ? _debugToggle(context) : null, + ); // Header, status and rows share one scroll view: the page never splits a // fixed header from a shrinking list, so a long header always stays usable. - final body = groups.isEmpty + final body = visibleGroups.isEmpty ? ListView(children: [header]) : ArtifactVisitList( header: header, - groups: groups, + groups: visibleGroups, selectedIdentity: _selectedIdentity, onSelected: _select, configuredEndpoint: widget.configuredEndpoint, fetch: widget.fetch, initiallyCollapsed: widget.initiallyCollapsed, + showTurnDocuments: _showTurnDocuments, ); if (widget.embedded) return body; if (usesCupertinoHost(context)) { // Flat sections on the page colour, as in the run and stage details; // their pinned headings take the same colour. return CupertinoPageScaffold( - navigationBar: const SegmentedBar( + navigationBar: SegmentedBar( cupertino: true, title: artifactGalleryTitle, + actions: [_debugToggle(context)], ), child: SafeArea(top: false, bottom: false, child: body), ); } return Scaffold( extendBodyBehindAppBar: true, - appBar: const SegmentedBar(cupertino: false, title: artifactGalleryTitle), + appBar: SegmentedBar( + cupertino: false, + title: artifactGalleryTitle, + actions: [_debugToggle(context)], + ), body: SafeArea(top: false, bottom: false, child: body), ); } diff --git a/app/lib/features/artifacts/ui/artifact_visit_list.dart b/app/lib/features/artifacts/ui/artifact_visit_list.dart index c53d8089..243370fd 100644 --- a/app/lib/features/artifacts/ui/artifact_visit_list.dart +++ b/app/lib/features/artifacts/ui/artifact_visit_list.dart @@ -22,10 +22,11 @@ export 'artifact_row_labels.dart' /// A read-only, selectable list of recorded artifact groups. /// -/// Each group shows its recorded stage and visit, its stage-produced artifacts, -/// then its turn documents. Every recorded row shows its recorded filename, -/// content type and size; a turn document the visit did not record stays a -/// non-actionable row with the exact absence wording. Rendering uses the host's +/// Each group shows its recorded stage and visit and its stage-produced +/// artifacts. When [showTurnDocuments] is on, its debugging documents follow +/// those artifacts in the same visit. Every recorded row shows its recorded +/// filename, content type and size; a turn document the visit did not record +/// stays a non-actionable row with the exact absence wording. Rendering uses the host's /// own controls: Material list tiles under [MaterialApp] and grouped Cupertino /// list sections under [CupertinoApp]. An optional [header] leads the same /// scroll view. It never resolves a url, opens a preview, downloads, shares or @@ -43,6 +44,7 @@ class ArtifactVisitList extends StatefulWidget { this.configuredEndpoint = '', this.fetch = fetchArtifact, this.initiallyCollapsed = true, + this.showTurnDocuments = false, }); final Widget? header; @@ -57,10 +59,12 @@ class ArtifactVisitList extends StatefulWidget { final String configuredEndpoint; final ArtifactFetch fetch; - /// Whether generated-artifact sections begin closed. Turn documents always - /// begin closed because they are debugging evidence. + /// Whether generated-artifact sections begin closed. final bool initiallyCollapsed; + /// Whether debugging documents are visible below their visit's artifacts. + final bool showTurnDocuments; + /// The layout last chosen, kept for the app's lifetime. static ArtifactGalleryMode lastMode = ArtifactGalleryMode.grid; @@ -83,12 +87,26 @@ class _ArtifactVisitListState extends State { for (final group in widget.groups) if (group.artifacts.isNotEmpty) '${group.stageKey}\u0000${group.visit}\u0000artifacts', - for (final group in widget.groups) - if (group.documents.isNotEmpty) - '${group.stageKey}\u0000${group.visit}\u0000documents', }; } + @override + void didUpdateWidget(covariant ArtifactVisitList oldWidget) { + super.didUpdateWidget(oldWidget); + // Embedded galleries begin with their visits collapsed. Debug must reveal + // the documents immediately rather than require a second tap on the visit + // heading. + if (!oldWidget.showTurnDocuments && widget.showTurnDocuments) { + for (final group in widget.groups) { + if (group.documents.isNotEmpty) { + _closed.remove( + '${group.stageKey}\u0000${group.visit}\u0000artifacts', + ); + } + } + } + } + void _toggle(String key) => setState(() { if (!_closed.remove(key)) _closed.add(key); }); @@ -116,7 +134,8 @@ class _ArtifactVisitListState extends State { ]; for (final group in widget.groups) { final identity = '${group.stageKey}\u0000${group.visit}'; - if (group.artifacts.isNotEmpty) { + if (group.artifacts.isNotEmpty || + (widget.showTurnDocuments && group.documents.isNotEmpty)) { final key = '$identity\u0000artifacts'; slivers.add( _section( @@ -124,30 +143,20 @@ class _ArtifactVisitListState extends State { key: key, title: artifactGroupLabel(group), count: group.artifacts.length, - body: _mode == ArtifactGalleryMode.grid - ? _grid(group) - : _list(group), - ), - ); - } - if (group.documents.isNotEmpty) { - final key = '$identity\u0000documents'; - slivers.add( - _section( - context, - key: key, - title: '${artifactGroupLabel(group)} · Turn documents', - count: group.documents.length, body: Column( crossAxisAlignment: CrossAxisAlignment.stretch, children: [ - _debugHint(context), - ArtifactDocumentSection( - group: group, - selectedIdentity: widget.selectedIdentity, - onSelected: widget.onSelected, - showHeader: false, - ), + if (group.artifacts.isNotEmpty) + _mode == ArtifactGalleryMode.grid + ? _grid(group) + : _list(group), + if (widget.showTurnDocuments && group.documents.isNotEmpty) + ArtifactDocumentSection( + group: group, + selectedIdentity: widget.selectedIdentity, + onSelected: widget.onSelected, + showHeader: false, + ), ], ), ), @@ -232,20 +241,6 @@ class _ArtifactVisitListState extends State { ); } - Widget _debugHint(BuildContext context) { - final style = usesCupertinoHost(context) - ? CupertinoTheme.of(context).textTheme.textStyle.copyWith( - color: CupertinoColors.secondaryLabel.resolveFrom(context), - ) - : Theme.of(context).textTheme.bodySmall?.copyWith( - color: Theme.of(context).colorScheme.onSurfaceVariant, - ); - return Padding( - padding: const EdgeInsetsDirectional.fromSTEB(16, 8, 16, 4), - child: Text('For debugging.', style: style), - ); - } - /// The list view: one row per artifact with a small thumbnail beside it. Widget _list(ArtifactGroup group) => Column( crossAxisAlignment: CrossAxisAlignment.stretch, diff --git a/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart index 258f351a..1c6ec0a3 100644 --- a/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart +++ b/app/test/features/artifacts/ui/artifact_gallery_documents_test.dart @@ -80,12 +80,9 @@ Future _pump( await tester.pumpAndSettle(); } -Future _expandTurnDocuments(WidgetTester tester) async { - final headings = find.textContaining('Turn documents'); - for (var index = 0; index < headings.evaluate().length; index += 1) { - await tester.tap(headings.at(index)); - await tester.pumpAndSettle(); - } +Future _showTurnDocuments(WidgetTester tester) async { + await tester.tap(find.byKey(const Key('artifact-debug-toggle'))); + await tester.pumpAndSettle(); } Finder _dialog(_Platform platform, String text) => find.descendant( @@ -97,16 +94,14 @@ Finder _dialog(_Platform platform, String text) => find.descendant( void main() { for (final platform in _Platform.values) { - testWidgets('${platform.name}: every recorded document is an entry', ( - tester, - ) async { + testWidgets('${platform.name}: debug hides documents by default and shows ' + 'each visit when enabled', (tester) async { await _pump(tester, platform); - expect(find.textContaining('Turn documents'), findsNWidgets(2)); - // The generated artifact grid remains primary; debugging evidence is - // deliberately hidden until its own section is opened. expect(find.text('input.md'), findsNothing); - expect(find.text('For debugging.'), findsNothing); - await _expandTurnDocuments(tester); + expect(find.textContaining('Turn documents'), findsNothing); + expect(find.byTooltip('Show turn documents'), findsOneWidget); + await _showTurnDocuments(tester); + expect(find.byTooltip('Hide turn documents'), findsOneWidget); expect(find.text('input.md'), findsNWidgets(2)); expect(find.text('output.md'), findsNWidgets(2)); expect(find.text('session.html'), findsNWidgets(2)); @@ -119,7 +114,7 @@ void main() { tester, ) async { await _pump(tester, platform); - await _expandTurnDocuments(tester); + await _showTurnDocuments(tester); expect(find.text('No memory recorded for this visit.'), findsOneWidget); expect(find.text('No output recorded.'), findsOneWidget); expect(find.text('This visit has no harness session.'), findsOneWidget); @@ -130,7 +125,7 @@ void main() { tester, ) async { await _pump(tester, platform); - await _expandTurnDocuments(tester); + await _showTurnDocuments(tester); await tester.tap(find.text('input.md').first); await tester.pumpAndSettle(); expect(find.byType(ArtifactViewerPage), findsOneWidget); @@ -145,7 +140,7 @@ void main() { '${platform.name}: absent rows are informational, not controls', (tester) async { await _pump(tester, platform); - await _expandTurnDocuments(tester); + await _showTurnDocuments(tester); final absence = find.text('No output recorded.'); expect(absence, findsOneWidget); if (platform == _Platform.material) { @@ -187,7 +182,7 @@ void main() { }, fetch: (_) async => throw StateError('x'), ); - await _expandTurnDocuments(tester); + await _showTurnDocuments(tester); await tester.tap(find.text('session.html').first); await tester.pumpAndSettle(); expect(find.byType(ArtifactViewerPage), findsNothing); @@ -226,8 +221,7 @@ void main() { expect(find.text('Artifact · 1 recorded'), findsOneWidget); expect(find.text('report.csv'), findsOneWidget); expect(find.text('input.md'), findsNothing); - await _expandTurnDocuments(tester); - expect(find.text('For debugging.'), findsOneWidget); + await _showTurnDocuments(tester); await tester.tap(find.text('input.md')); await tester.pumpAndSettle(); expect(find.byType(ArtifactViewerPage), findsOneWidget); @@ -252,9 +246,8 @@ void main() { expect(find.text('No artifacts recorded for this run.'), findsOneWidget); expect(find.text('input.md'), findsNothing); - await _expandTurnDocuments(tester); + await _showTurnDocuments(tester); expect(find.text('input.md'), findsOneWidget); - expect(find.text('For debugging.'), findsOneWidget); }); testWidgets('${platform.name}: focused document-only visits retain turn ' @@ -279,9 +272,8 @@ void main() { findsOneWidget, ); expect(find.text('input.md'), findsNothing); - await _expandTurnDocuments(tester); + await _showTurnDocuments(tester); expect(find.text('input.md'), findsOneWidget); - expect(find.text('For debugging.'), findsOneWidget); }); testWidgets('${platform.name}: focused visits retain session documents', ( @@ -290,9 +282,8 @@ void main() { await _pump(tester, platform, focusIndex: 0); expect(find.text('session.html'), findsNothing); - await _expandTurnDocuments(tester); + await _showTurnDocuments(tester); expect(find.text('session.html'), findsOneWidget); - expect(find.text('For debugging.'), findsOneWidget); }); } } diff --git a/app/test/features/runs/ui/run_detail_visit_sections_test.dart b/app/test/features/runs/ui/run_detail_visit_sections_test.dart index 08758d06..1de88acb 100644 --- a/app/test/features/runs/ui/run_detail_visit_sections_test.dart +++ b/app/test/features/runs/ui/run_detail_visit_sections_test.dart @@ -12,7 +12,7 @@ import 'package:pipelines_app/ui/layout/sticky_section.dart'; import 'run_detail_graph_support.dart'; import 'run_detail_visit_support.dart'; -Future _expandArtifactGroup(WidgetTester tester) async { +Future _expandArtifactGroups(WidgetTester tester) async { final sections = find.byType(StickySectionTitle); for (var index = 0; index < sections.evaluate().length; index += 1) { await tester.tap(sections.at(index)); @@ -20,6 +20,11 @@ Future _expandArtifactGroup(WidgetTester tester) async { await tester.pumpAndSettle(); } +Future _showTurnDocuments(WidgetTester tester) async { + await tester.tap(find.byKey(const Key('artifact-debug-toggle'))); + await tester.pumpAndSettle(); +} + void main() { for (final platform in RunDetailTestPlatform.values) { testWidgets('${platform.name} stage tabs sit at the bottom with one Back', ( @@ -79,12 +84,15 @@ void main() { expect(find.text('ok'), findsOneWidget); await openVisitTab(tester, RunVisitSection.artifacts); - // The focused gallery keeps generated files primary and makes the session - // evidence reachable in its secondary turn-documents section. - await _expandArtifactGroup(tester); + // The focused gallery keeps generated files primary until debugging is + // explicitly enabled. expect(find.byType(ArtifactGalleryPage), findsOneWidget); - expect(find.text('plan.csv'), findsOneWidget); + expect(find.text('session.html'), findsNothing); + await _showTurnDocuments(tester); + // Embedded visit sections begin collapsed. Debug opens the visit so its + // diagnostic documents do not require a second tap on the heading. expect(find.text('session.html'), findsOneWidget); + expect(find.text('plan.csv'), findsOneWidget); await openVisitTab(tester, RunVisitSection.session); expect(find.text('Session'), findsWidgets); @@ -196,7 +204,7 @@ void main() { await openVisit(tester, platform, run: run, sequence: 2); expectVisitHeading(tester, 'plan', 2); await openVisitTab(tester, RunVisitSection.artifacts); - await _expandArtifactGroup(tester); + await _expandArtifactGroups(tester); expect(find.text('plan-2.csv'), findsOneWidget); expect(find.text('public/shared.csv'), findsNothing); expect(find.byType(ArtifactGalleryPage), findsOneWidget);