feat(app): add debug toggle for turn documents

This commit is contained in:
2026-10-31 15:22:33 +00:00
parent 6962d0bfe0
commit f84948153b
4 changed files with 137 additions and 87 deletions
@@ -89,6 +89,7 @@ class _ArtifactGalleryPageState extends State<ArtifactGalleryPage> {
late final List<ArtifactGroup> _groups = _groupsOf(widget.focusIndex);
String? _selectedIdentity;
String? _status;
bool _showTurnDocuments = false;
List<ArtifactGroup> _groupsOf(int? focusIndex) {
final allGroups = _withRepairDocuments(galleryGroups(widget.steps));
@@ -436,7 +437,7 @@ class _ArtifactGalleryPageState extends State<ArtifactGalleryPage> {
/// 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<ArtifactGalleryPage> {
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<ArtifactGalleryPage> {
);
}
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),
);
}
@@ -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<ArtifactVisitList> {
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<ArtifactVisitList> {
];
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<ArtifactVisitList> {
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<ArtifactVisitList> {
);
}
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,
@@ -80,12 +80,9 @@ Future<void> _pump(
await tester.pumpAndSettle();
}
Future<void> _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<void> _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);
});
}
}
@@ -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<void> _expandArtifactGroup(WidgetTester tester) async {
Future<void> _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<void> _expandArtifactGroup(WidgetTester tester) async {
await tester.pumpAndSettle();
}
Future<void> _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);