From f57d8eeb76f1d6ff154e6e1437c4c8fc5886e1fd Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 10:48:36 +0100 Subject: [PATCH] feat(app): open a recorded run visit from its URL `/runs/:id/stage/:key?visit=N` now selects that stage's N-th recorded visit in the run detail Timeline, matching the web client's stage-local visit ordering. A stage key without a visit opens the latest recorded visit, an out-of-range index clamps to the last one, and a stage with no recorded visit selects only its Graph node instead of inventing a visit. Route plumbing carries the query end to end: boot seeds the router from path and query, the parser reads path plus query, and restore keeps `?` a query separator instead of percent-encoding it. That also repairs the existing `?action=decide` and `/runs?pipeline=` URLs. The Graph node click and the stage route share one sequence-ordered resolver, so both open the same latest visit. --- app/lib/application/app_router.dart | 34 +- app/lib/application/pipelines_app.dart | 11 +- app/lib/application/runs_destination.dart | 11 + app/lib/features/runs/screen.dart | 9 + .../runs/ui/run_detail_cupertino.dart | 4 + .../features/runs/ui/run_detail_material.dart | 4 + app/lib/features/runs/ui/run_detail_tabs.dart | 66 +++- app/lib/features/runs/ui/run_detail_view.dart | 12 + .../runs/ui/run_detail_visit_facts.dart | 42 ++- app/test/application/app_router_test.dart | 51 +++ app/test/application/pipelines_app_test.dart | 96 ++++++ .../runs/ui/run_detail_deep_link_test.dart | 301 ++++++++++++++++++ 12 files changed, 623 insertions(+), 18 deletions(-) create mode 100644 app/test/features/runs/ui/run_detail_deep_link_test.dart diff --git a/app/lib/application/app_router.dart b/app/lib/application/app_router.dart index 581c4e78..b5814ed3 100644 --- a/app/lib/application/app_router.dart +++ b/app/lib/application/app_router.dart @@ -11,13 +11,24 @@ class AppRouteParser extends RouteInformationParser { @override Future parseRouteInformation( RouteInformation routeInformation, - ) async => AppRoute.parse(routeInformation.uri.path); + ) async => AppRoute.parse(routeLocation(routeInformation.uri)); @override RouteInformation restoreRouteInformation(AppRoute configuration) => - RouteInformation(uri: Uri(path: configuration.path)); + // The route's path already carries its query (`?visit=N`, `?action=…`). + // Parsing it keeps that query a query instead of percent-encoding the + // `?` into the path, which would make a reload read one bogus key. + RouteInformation(uri: Uri.parse(configuration.path)); } +/// The app-relative location of [uri]: its path plus query, without origin. +/// +/// [AppRoute.parse] understands this form, so a browser location such as +/// `/runs/7/stage/plan?visit=1` keeps the query instead of losing it to +/// `Uri.path`. A fragment is not part of an app route. +String routeLocation(Uri uri) => + uri.hasQuery ? '${uri.path}?${uri.query}' : uri.path; + /// Owns the app's current route and builds the shell for it. /// /// Route changes made by the operator go through [goTo]; the Router reports @@ -190,10 +201,21 @@ class AppRouterDelegate extends RouterDelegate with ChangeNotifier { /// The location a web launch starts at, or the Pipelines list elsewhere. /// -/// Only the path is meaningful to [AppRouteParser]; the origin stays out of -/// route configuration so a serialised route is always app-relative. +/// The origin stays out of route configuration so a serialised route is always +/// app-relative, but the path and its query are both part of the route: a +/// launch at `/runs/7/stage/plan?visit=1` must open exactly that visit. RouteInformation initialRouteInformation() { if (!kIsWeb) return RouteInformation(uri: Uri(path: '/pipelines')); - final path = Uri.base.path; - return RouteInformation(uri: Uri(path: path.isEmpty ? '/' : path)); + return routeInformationForLocation(Uri.base); +} + +/// The app-relative route information for a browser [base] location. +/// +/// Exposed for the boot test: [Uri.base] cannot be changed inside a widget +/// test, so the web launch seam is exercised through this function. +@visibleForTesting +RouteInformation routeInformationForLocation(Uri base) { + final path = base.path.isEmpty ? '/' : base.path; + final query = base.hasQuery ? '?${base.query}' : ''; + return RouteInformation(uri: Uri.parse('$path$query')); } diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index 7e6af5ea..ab251a8a 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -82,10 +82,13 @@ class _PipelinesAppState extends State { ); // A malformed or unknown boot path renders Pipelines, so make the address // bar agree with the rendered destination instead of showing a dead link. - final initial = AppRoute.parse(_provider.value.uri.path); - if (_provider.value.uri.path != initial.path) { + // The comparison includes the query: `?visit=N` is part of the route, while + // a dropped or unknown query is canonicalised away. + final location = routeLocation(_provider.value.uri); + final initial = AppRoute.parse(location); + if (location != initial.path) { _provider.routerReportsNewRouteInformation( - RouteInformation(uri: Uri(path: initial.path)), + RouteInformation(uri: Uri.parse(initial.path)), type: RouteInformationReportingType.neglect, ); } @@ -208,6 +211,8 @@ class _PipelinesAppState extends State { session: _session, server: widget.server, initialRunId: route.runId, + initialStageKey: route.stageKey, + initialVisit: route.visit, listRefreshToken: _runsRefresh, notifications: _notifications, onRunSelected: (id) => _delegate.goTo(AppRoute.run(id)), diff --git a/app/lib/application/runs_destination.dart b/app/lib/application/runs_destination.dart index fdef966e..e5270d88 100644 --- a/app/lib/application/runs_destination.dart +++ b/app/lib/application/runs_destination.dart @@ -19,6 +19,8 @@ class RunsDestination extends StatelessWidget { required this.session, required this.server, this.initialRunId, + this.initialStageKey, + this.initialVisit, this.onRunSelected, this.onBack, this.listRefreshToken = 0, @@ -28,6 +30,13 @@ class RunsDestination extends StatelessWidget { final AppSession session; final ServerEndpoint server; final int? initialRunId; + + /// The stage key and optional visit a `/runs/:id/stage/:key[?visit=N]` route + /// names. They reach the detail only through [RunsScreen]; the destination + /// does not read the route itself. + final String? initialStageKey; + final int? initialVisit; + final ValueChanged? onRunSelected; final VoidCallback? onBack; @@ -73,6 +82,8 @@ class RunsDestination extends StatelessWidget { Widget _runsScreen() => RunsScreen( gateway: session.gateway, initialRunId: initialRunId, + initialStageKey: initialStageKey, + initialVisit: initialVisit, syncToken: session.connectionEpoch, listRefreshToken: listRefreshToken, notifications: notifications, diff --git a/app/lib/features/runs/screen.dart b/app/lib/features/runs/screen.dart index 56dc70a7..e6ae2c14 100644 --- a/app/lib/features/runs/screen.dart +++ b/app/lib/features/runs/screen.dart @@ -19,6 +19,8 @@ class RunsScreen extends StatefulWidget { super.key, required this.gateway, this.initialRunId, + this.initialStageKey, + this.initialVisit, this.syncToken = 0, this.listRefreshToken = 0, this.onRunSelected, @@ -33,6 +35,11 @@ class RunsScreen extends StatefulWidget { /// The run the current route names, or null for the list. final int? initialRunId; + /// The recorded stage visit the route names inside [initialRunId]. The detail + /// applies it once per route target; the feature never invents a visit. + final String? initialStageKey; + final int? initialVisit; + /// Advances when the shared socket is replaced. The loaded screen refreshes /// in place instead of being remounted, so its selection survives. final int syncToken; @@ -143,6 +150,8 @@ class _RunsScreenState extends State { gateway: widget.gateway, onBack: _back, onRunOpened: _select, + initialStageKey: widget.initialStageKey, + initialVisit: widget.initialVisit, ), ], ); diff --git a/app/lib/features/runs/ui/run_detail_cupertino.dart b/app/lib/features/runs/ui/run_detail_cupertino.dart index 4da3afa0..ea4f80b4 100644 --- a/app/lib/features/runs/ui/run_detail_cupertino.dart +++ b/app/lib/features/runs/ui/run_detail_cupertino.dart @@ -21,6 +21,8 @@ Widget buildCupertinoRunDetail({ required VoidCallback onBack, required VoidCallback onCopy, required String configuredEndpoint, + String? initialStageKey, + int? initialVisit, }) { final theme = CupertinoTheme.of(context); return RunDetailTabs( @@ -30,6 +32,8 @@ Widget buildCupertinoRunDetail({ copyStatus: copyStatus, onCopy: onCopy, configuredEndpoint: configuredEndpoint, + initialStageKey: initialStageKey, + initialVisit: initialVisit, header: Column( crossAxisAlignment: CrossAxisAlignment.stretch, children: [ diff --git a/app/lib/features/runs/ui/run_detail_material.dart b/app/lib/features/runs/ui/run_detail_material.dart index 8d27e80e..34bbca4e 100644 --- a/app/lib/features/runs/ui/run_detail_material.dart +++ b/app/lib/features/runs/ui/run_detail_material.dart @@ -21,6 +21,8 @@ Widget buildMaterialRunDetail({ required VoidCallback onBack, required VoidCallback onCopy, required String configuredEndpoint, + String? initialStageKey, + int? initialVisit, }) { final theme = Theme.of(context); return RunDetailTabs( @@ -30,6 +32,8 @@ Widget buildMaterialRunDetail({ copyStatus: copyStatus, onCopy: onCopy, configuredEndpoint: configuredEndpoint, + initialStageKey: initialStageKey, + initialVisit: initialVisit, header: Column( crossAxisAlignment: CrossAxisAlignment.stretch, children: [ diff --git a/app/lib/features/runs/ui/run_detail_tabs.dart b/app/lib/features/runs/ui/run_detail_tabs.dart index 6641994b..cc03c320 100644 --- a/app/lib/features/runs/ui/run_detail_tabs.dart +++ b/app/lib/features/runs/ui/run_detail_tabs.dart @@ -37,6 +37,8 @@ class RunDetailTabs extends StatefulWidget { required this.copyStatus, required this.onCopy, required this.configuredEndpoint, + this.initialStageKey, + this.initialVisit, }); final JsonMap run; @@ -54,6 +56,15 @@ class RunDetailTabs extends StatefulWidget { /// through the landed safe-link helper. Blank leaves relative urls unresolved. final String configuredEndpoint; + /// The stage a `/runs/:id/stage/:key` route names, or null for the plain + /// detail. It selects a recorded visit; a declared but unvisited stage only + /// selects its graph node, so no visit is ever invented. + final String? initialStageKey; + + /// The zero-based index among [initialStageKey]'s recorded visits. Null opens + /// the stage's latest visit, exactly as a Graph node click does. + final int? initialVisit; + @override State createState() => _RunDetailTabsState(); } @@ -63,15 +74,68 @@ class _RunDetailTabsState extends State { String? _selectedStage; int? _selectedVisit; + @override + void initState() { + super.initState(); + _applyInitialVisit(); + } + @override void didUpdateWidget(covariant RunDetailTabs oldWidget) { super.didUpdateWidget(oldWidget); + final sameRun = '${widget.run['id']}' == '${oldWidget.run['id']}'; + final sameTarget = + widget.initialStageKey == oldWidget.initialStageKey && + widget.initialVisit == oldWidget.initialVisit; // A different run is a different detail: its visits and graph do not carry // the previous run's selection. - if ('${widget.run['id']}' != '${oldWidget.run['id']}') { + if (!sameRun) { _tab = RunDetailTab.summary; _selectedStage = null; _selectedVisit = null; + _applyInitialVisit(); + } else if (!sameTarget) { + // A route that names another stage or visit is applied to the same run. + // Rebuilds from a live refresh keep the operator's own selection. + _applyInitialVisit(); + } + } + + /// Opens the visit a route names, without presenting any visit the run did + /// not record. + /// + /// A route with a stage key and no visit opens that stage's latest recorded + /// visit, the same visit a Graph node click opens. A valid index selects that + /// visit among the stage's own visits; an out-of-range index is clamped to the + /// stage's last recorded visit, as the web client does, so the address bar and + /// the pane never disagree about which visit is real. A declared but + /// unvisited stage selects its Graph node only. + void _applyInitialVisit() { + final stageKey = widget.initialStageKey; + if (stageKey == null || stageKey.isEmpty) { + _selectedStage = null; + _selectedVisit = null; + return; + } + final index = routeDetailVisitIndex( + widget.run['steps'], + stageKey, + widget.initialVisit, + ); + if (index != null) { + _selectedStage = stageKey; + _selectedVisit = index; + _tab = RunDetailTab.timeline; + return; + } + _selectedVisit = null; + // The key is not a recorded visit. Only a stage the pinned graph actually + // declares can be selected; anything else leaves the plain detail intact. + if (detailVisitHasDefinition(detailGraph(widget.run), stageKey)) { + _selectedStage = stageKey; + _tab = RunDetailTab.graph; + } else { + _selectedStage = null; } } diff --git a/app/lib/features/runs/ui/run_detail_view.dart b/app/lib/features/runs/ui/run_detail_view.dart index 6e2bbcb9..b5988b90 100644 --- a/app/lib/features/runs/ui/run_detail_view.dart +++ b/app/lib/features/runs/ui/run_detail_view.dart @@ -18,6 +18,8 @@ class RunDetailView extends StatefulWidget { required this.gateway, required this.onBack, this.onRunOpened, + this.initialStageKey, + this.initialVisit, }); final RunsController controller; @@ -30,6 +32,12 @@ class RunDetailView extends StatefulWidget { /// the server-identified new run. Null keeps the detail on the retried run. final ValueChanged? onRunOpened; + /// The route's stage and visit, forwarded to the tab body so a `/runs/:id/ + /// stage/:key[?visit=N]` deep link opens that recorded visit. Null is the + /// plain detail. + final String? initialStageKey; + final int? initialVisit; + @override State createState() => _RunDetailViewState(); } @@ -65,6 +73,8 @@ class _RunDetailViewState extends State { onBack: widget.onBack, onCopy: () => _copyPrompt(prompt ?? '', cupertino: true), configuredEndpoint: endpoint, + initialStageKey: widget.initialStageKey, + initialVisit: widget.initialVisit, ) : buildMaterialRunDetail( context: context, @@ -77,6 +87,8 @@ class _RunDetailViewState extends State { onBack: widget.onBack, onCopy: () => _copyPrompt(prompt ?? '', cupertino: false), configuredEndpoint: endpoint, + initialStageKey: widget.initialStageKey, + initialVisit: widget.initialVisit, ); }, ); diff --git a/app/lib/features/runs/ui/run_detail_visit_facts.dart b/app/lib/features/runs/ui/run_detail_visit_facts.dart index b26dfa4a..a631d183 100644 --- a/app/lib/features/runs/ui/run_detail_visit_facts.dart +++ b/app/lib/features/runs/ui/run_detail_visit_facts.dart @@ -31,15 +31,41 @@ JsonMap? detailVisitStepAt(JsonMap run, int index) { } /// The row index of [stageKey]'s latest recorded visit, or null when the run -/// never recorded that stage. It reads the same ordered timeline the rows do, -/// so a Graph click opens exactly the row the operator would have selected. -int? latestDetailVisitIndex(dynamic steps, String stageKey) { +/// never recorded that stage. +/// +/// The order matches [routeDetailVisitIndex] and the web client's +/// `visitsByStage`: a stage's visits follow their recorded sequence, not their +/// position in the reply's step list. So a Graph click and `/runs/:id/stage/:key` +/// open the same visit even when the steps are not in sequence order. +int? latestDetailVisitIndex(dynamic steps, String stageKey) => + routeDetailVisitIndex(steps, stageKey, null); + +/// The timeline row index a route's [stageKey] and [visit] name, or null when +/// the run recorded no visit of that stage. +/// +/// A stage's visits follow their recorded sequence, as the web client's +/// `visitsByStage` does, so the same `?visit=N` selects the same visit in both +/// clients while equal sequences keep the timeline's own order. A null [visit] +/// is the stage's last recorded visit, the one a Graph node click opens; an +/// out-of-range index is clamped to that last visit, exactly as the web client +/// clamps it. Nothing is invented for a stage with no recorded visit. +int? routeDetailVisitIndex(dynamic steps, String stageKey, int? visit) { final visits = detailTimeline(steps); - int? latest; - for (var index = 0; index < visits.length; index += 1) { - if (visits[index].stage == stageKey) latest = index; - } - return latest; + final indices = [ + for (var index = 0; index < visits.length; index += 1) + if (visits[index].stage == stageKey) index, + ]; + if (indices.isEmpty) return null; + indices.sort((a, b) { + final bySequence = (visits[a].sequence ?? 0).compareTo( + visits[b].sequence ?? 0, + ); + return bySequence != 0 ? bySequence : a.compareTo(b); + }); + final wanted = visit == null + ? indices.length - 1 + : visit.clamp(0, indices.length - 1); + return indices[wanted]; } /// The visit's recorded facts, in the pane's order. A field the server did not diff --git a/app/test/application/app_router_test.dart b/app/test/application/app_router_test.dart index 1c5c3731..d746433e 100644 --- a/app/test/application/app_router_test.dart +++ b/app/test/application/app_router_test.dart @@ -49,4 +49,55 @@ void main() { router.closeTemplates(); expect(router.route, AppRoute.settings); }); + + test('the parser keeps a query and restores it as a query', () async { + const parser = AppRouteParser(); + final route = await parser.parseRouteInformation( + RouteInformation(uri: Uri.parse('/runs/77/stage/plan?visit=1')), + ); + expect(route, AppRoute.run.stage(77, 'plan', visit: 1)); + + final restored = parser.restoreRouteInformation(route).uri; + expect(restored.path, '/runs/77/stage/plan'); + expect(restored.query, 'visit=1'); + expect(restored.toString(), '/runs/77/stage/plan?visit=1'); + // A reload or Back/Forward feeds the restored location straight back in. + expect(AppRoute.parse(restored.toString()), route); + }); + + test('every query route survives a restore and reparse', () { + const parser = AppRouteParser(); + for (final route in [ + AppRoute.runsForPipeline(7), + AppRoute.run.decide(3), + AppRoute.run.stage(3, 'plan', visit: 0), + AppRoute.run.stage(5, 'build ✓', visit: 4), + ]) { + final uri = parser.restoreRouteInformation(route).uri; + expect(uri.toString(), route.path, reason: route.path); + expect(uri.path, isNot(contains('%3F')), reason: route.path); + expect(AppRoute.parse(uri.toString()), route, reason: route.path); + } + }); + + test('a web launch keeps the path and its query', () { + final visit = routeInformationForLocation( + Uri.parse('https://example.test/runs/7/stage/plan?visit=2'), + ); + expect(visit.uri.toString(), '/runs/7/stage/plan?visit=2'); + expect(visit.uri.path, '/runs/7/stage/plan'); + expect(visit.uri.query, 'visit=2'); + + final decide = routeInformationForLocation( + Uri.parse('https://example.test/runs/9?action=decide'), + ); + expect(decide.uri.toString(), '/runs/9?action=decide'); + + expect( + routeInformationForLocation( + Uri.parse('https://example.test/'), + ).uri.toString(), + '/', + ); + }); } diff --git a/app/test/application/pipelines_app_test.dart b/app/test/application/pipelines_app_test.dart index 81e526d8..a9812d67 100644 --- a/app/test/application/pipelines_app_test.dart +++ b/app/test/application/pipelines_app_test.dart @@ -2,6 +2,8 @@ import 'dart:convert'; import 'package:flutter/widgets.dart'; import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/application/app_route.dart'; +import 'package:pipelines_app/application/app_router.dart'; import 'package:pipelines_app/application/pipelines_app.dart'; import 'package:pipelines_app/application/server_endpoint.dart'; import 'package:pipelines_app/core/transport/pipelines_client.dart'; @@ -84,6 +86,57 @@ Future replyDetail( await tester.pump(); } +/// A run whose plan visits are deliberately not in sequence order, so a route +/// visit index must follow the recorded sequence, not the reply's row order. +Future replyVisitDetail( + WidgetTester tester, + FakeChannel channel, + num id, +) async { + for ( + var attempt = 0; + attempt < 40 && requestOf(channel, 'get_run') == null; + attempt++ + ) { + await tester.pump(const Duration(milliseconds: 5)); + } + final request = requestOf(channel, 'get_run')!; + expect(request['run_id'], id); + channel.incoming.add( + jsonEncode({ + 'id': request['id'], + 'type': 'run', + 'run_detail': { + 'id': id, + 'title': 'Deep link run', + 'name': 'release', + 'status': 'succeeded', + 'graph': { + 'stages': [ + { + 'key': 'plan', + 'type': 'model', + 'edges': {'success': 'build'}, + }, + { + 'key': 'build', + 'type': 'model', + 'edges': {'success': '#success'}, + }, + ], + }, + 'steps': [ + {'stage': 'plan', 'sequence': 5, 'status': 'completed'}, + {'stage': 'build', 'sequence': 2, 'status': 'completed'}, + {'stage': 'plan', 'sequence': 1, 'status': 'completed'}, + ], + }, + }), + ); + await tester.pump(); + await tester.pump(); +} + void main() { testWidgets('a /runs/1 boot link opens that run and Back returns to /runs', ( tester, @@ -195,4 +248,47 @@ void main() { await tester.pumpWidget(const SizedBox.shrink()); await tester.pump(); }); + + testWidgets('a queried stage boot link opens that exact recorded visit', ( + tester, + ) async { + final channel = FakeChannel()..readyCompleter.complete(); + final client = PipelinesClient(channelFactory: (_) => channel); + final provider = PlatformRouteInformationProvider( + initialRouteInformation: RouteInformation( + uri: Uri.parse('/runs/77/stage/plan?visit=0'), + ), + ); + addTearDown(provider.dispose); + + await pumpApp(tester, channel: channel, client: client, provider: provider); + await replyList( + tester, + channel, + runs: [ + {'id': 77, 'name': 'Deep link run', 'status': 'succeeded'}, + ], + ); + await replyVisitDetail(tester, channel, 77); + + // The query reached the detail: visit 0 is the earlier plan visit (seq 1), + // not the latest one the pane would show without a visit. + expect(find.byKey(const Key('run-visit-pane')), findsOneWidget); + expect(find.text('plan · visit 1'), findsOneWidget); + expect(find.text('plan · visit 5'), findsNothing); + expect(provider.value.uri.toString(), '/runs/77/stage/plan?visit=0'); + + // A history entry the app itself writes is parsed back as a query, so + // Back/Forward (and a reload) open the visit instead of a bogus stage key. + final restored = const AppRouteParser() + .restoreRouteInformation(AppRoute.run.stage(77, 'plan', visit: 1)) + .uri; + expect(restored.toString(), '/runs/77/stage/plan?visit=1'); + await provider.didPushRouteInformation(RouteInformation(uri: restored)); + await tester.pump(); + await tester.pump(); + expect(find.text('plan · visit 5'), findsOneWidget); + expect(provider.value.uri.path, '/runs/77/stage/plan'); + expect(provider.value.uri.query, 'visit=1'); + }); } diff --git a/app/test/features/runs/ui/run_detail_deep_link_test.dart b/app/test/features/runs/ui/run_detail_deep_link_test.dart new file mode 100644 index 00000000..f85b7843 --- /dev/null +++ b/app/test/features/runs/ui/run_detail_deep_link_test.dart @@ -0,0 +1,301 @@ +import 'dart:async'; + +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/graph/widgets/run_graph_view.dart'; +import 'package:pipelines_app/features/runs/data/runs_repository.dart'; +import 'package:pipelines_app/features/runs/screen.dart'; +import 'package:pipelines_app/features/runs/ui/run_detail_tab.dart'; +import 'package:pipelines_app/features/runs/ui/run_detail_view.dart'; +import 'package:pipelines_app/features/runs/ui/runs_controller.dart'; + +import 'run_detail_graph_support.dart'; + +/// plan -> build -> audit, with two recorded plan visits and one build visit. +/// +/// The steps are deliberately not in sequence order, so a stage visit index +/// must follow the visit's recorded sequence while the row index follows the +/// timeline's step order. +JsonMap deepLinkRunFixture() => { + 'id': 77, + 'title': 'Deep link run', + 'name': 'release', + 'status': 'succeeded', + 'input': {'prompt': 'ship it'}, + 'graph': { + 'stages': [ + { + 'key': 'plan', + 'type': 'model', + 'edges': {'success': 'build', 'error': '#'}, + }, + { + 'key': 'build', + 'type': 'model', + 'edges': {'success': 'audit', 'error': '#'}, + }, + { + 'key': 'audit', + 'type': 'model', + 'edges': {'success': '#success'}, + }, + ], + }, + 'steps': [ + { + 'stage': 'plan', + 'sequence': 5, + 'status': 'completed', + 'outcome': 'success', + }, + { + 'stage': 'build', + 'sequence': 2, + 'status': 'completed', + 'outcome': 'success', + }, + { + 'stage': 'plan', + 'sequence': 1, + 'status': 'completed', + 'outcome': 'success', + }, + ], +}; + +Future pumpDeepLink( + WidgetTester tester, + RunDetailTestPlatform platform, { + String? stage, + int? visit, + JsonMap? run, +}) async { + tester.view.physicalSize = const Size(900, 1000); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.reset); + final gateway = RunDetailFakeGateway(run ?? deepLinkRunFixture()); + final controller = RunsController(RunsRepository(gateway)); + addTearDown(controller.dispose); + await controller.select(77); + final view = RunDetailView( + controller: controller, + gateway: gateway, + onBack: () {}, + initialStageKey: stage, + initialVisit: visit, + ); + final page = MediaQuery( + data: MediaQueryData.fromView(tester.view), + child: view, + ); + await tester.pumpWidget(const SizedBox.shrink()); + await tester.pumpWidget( + platform == RunDetailTestPlatform.material + ? MaterialApp(home: Scaffold(body: page)) + : CupertinoApp( + home: CupertinoPageScaffold(child: SafeArea(child: page)), + ), + ); + await tester.pumpAndSettle(); +} + +/// The Runs screen's own request seam: a route-named run opens through the same +/// list-then-detail read the shell performs. +class _ScreenGateway implements ApiGateway { + final _frames = StreamController.broadcast(); + final listRequests = >[]; + final detailRequests = >[]; + + @override + Stream get frames => _frames.stream; + + @override + Future call(String type, [JsonMap fields = const {}]) { + final request = Completer(); + if (type == 'list_runs') { + listRequests.add(request); + } else if (type == 'get_run') { + detailRequests.add(request); + } else { + request.completeError(UnsupportedError(type)); + } + return request.future; + } + + void close() => _frames.close(); +} + +void main() { + for (final platform in RunDetailTestPlatform.values) { + testWidgets('${platform.name} stage visit opens that recorded visit', ( + tester, + ) async { + await pumpDeepLink(tester, platform, stage: 'plan', visit: 0); + + expect(find.byKey(const Key('run-visit-pane')), findsOneWidget); + expect(find.text('plan · visit 1'), findsOneWidget); + expect(find.text('plan · visit 5'), findsNothing); + expect( + find.byKey(const Key('run-detail-tab-body-timeline')), + findsWidgets, + ); + }); + + testWidgets('${platform.name} unknown stage opens the plain detail', ( + tester, + ) async { + await pumpDeepLink(tester, platform, stage: 'missing', visit: 2); + + expect(find.byKey(const Key('run-visit-pane')), findsNothing); + expect( + find.byKey(const Key('run-detail-tab-body-summary')), + findsOneWidget, + ); + expect(find.text('Deep link run'), findsOneWidget); + }); + + testWidgets('${platform.name} no stage key keeps the plain detail', ( + tester, + ) async { + await pumpDeepLink(tester, platform); + + expect(find.byKey(const Key('run-visit-pane')), findsNothing); + expect( + find.byKey(const Key('run-detail-tab-body-summary')), + findsOneWidget, + ); + }); + } + + testWidgets('a stage key without a visit opens that stage latest visit', ( + tester, + ) async { + await pumpDeepLink(tester, RunDetailTestPlatform.material, stage: 'plan'); + + expect(find.byKey(const Key('run-visit-pane')), findsOneWidget); + expect(find.text('plan · visit 5'), findsOneWidget); + }); + + testWidgets('a Graph click opens the same latest visit as the stage route', ( + tester, + ) async { + await pumpDeepLink(tester, RunDetailTestPlatform.material); + await openRunDetailTab(tester, RunDetailTab.graph); + await tapGraphNode(tester, 'plan'); + await tester.pumpAndSettle(); + + // The web client's graph click takes the last visit in sequence order, not + // the last row in reply order, so both entry points agree. + expect(find.byKey(const Key('run-visit-pane')), findsOneWidget); + expect(find.text('plan · visit 5'), findsOneWidget); + }); + + testWidgets('an out-of-range visit is clamped to the stage last visit', ( + tester, + ) async { + await pumpDeepLink( + tester, + RunDetailTestPlatform.material, + stage: 'plan', + visit: 9, + ); + + expect(find.byKey(const Key('run-visit-pane')), findsOneWidget); + expect(find.text('plan · visit 5'), findsOneWidget); + }); + + testWidgets('a declared but unvisited stage selects its graph node', ( + tester, + ) async { + await pumpDeepLink(tester, RunDetailTestPlatform.material, stage: 'audit'); + + expect(find.byKey(const Key('run-visit-pane')), findsNothing); + expect(find.byKey(const Key('run-detail-graph')), findsOneWidget); + final graph = tester.widget( + find.byKey(const Key('run-detail-graph')), + ); + expect(graph.selectedStage, 'audit'); + }); + + testWidgets('the Runs screen forwards the route stage and visit', ( + tester, + ) async { + final gateway = _ScreenGateway(); + addTearDown(gateway.close); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: RunsScreen( + gateway: gateway, + initialRunId: 77, + initialStageKey: 'plan', + initialVisit: 1, + ), + ), + ), + ); + await tester.pump(); + gateway.listRequests.single.complete({ + 'runs': [ + {'id': 77, 'title': 'Deep link run', 'status': 'succeeded'}, + ], + }); + await tester.pump(); + await tester.pump(); + gateway.detailRequests.single.complete({ + 'run_detail': deepLinkRunFixture(), + }); + await tester.pumpAndSettle(); + + expect(find.byKey(const Key('run-visit-pane')), findsOneWidget); + expect(find.text('plan · visit 5'), findsOneWidget); + }); + + testWidgets('a route change applies its visit and a plain route closes it', ( + tester, + ) async { + tester.view.physicalSize = const Size(900, 1000); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.reset); + final gateway = RunDetailFakeGateway(deepLinkRunFixture()); + final controller = RunsController(RunsRepository(gateway)); + addTearDown(controller.dispose); + await controller.select(77); + String? stage = 'plan'; + int? visit = 0; + late StateSetter rebuild; + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: StatefulBuilder( + builder: (context, setState) { + rebuild = setState; + return MediaQuery( + data: MediaQueryData.fromView(tester.view), + child: RunDetailView( + controller: controller, + gateway: gateway, + onBack: () {}, + initialStageKey: stage, + initialVisit: visit, + ), + ); + }, + ), + ), + ), + ); + await tester.pumpAndSettle(); + expect(find.text('plan · visit 1'), findsOneWidget); + + rebuild(() => visit = 1); + await tester.pumpAndSettle(); + expect(find.text('plan · visit 5'), findsOneWidget); + + rebuild(() => stage = null); + await tester.pumpAndSettle(); + expect(find.byKey(const Key('run-visit-pane')), findsNothing); + }); +}