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.
This commit is contained in:
2026-10-22 10:48:36 +01:00
parent 7aa7007aee
commit f57d8eeb76
12 changed files with 623 additions and 18 deletions
+51
View File
@@ -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(),
'/',
);
});
}
@@ -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<void> 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<void> 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');
});
}
@@ -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() => <String, dynamic>{
'id': 77,
'title': 'Deep link run',
'name': 'release',
'status': 'succeeded',
'input': <String, dynamic>{'prompt': 'ship it'},
'graph': <String, dynamic>{
'stages': <dynamic>[
<String, dynamic>{
'key': 'plan',
'type': 'model',
'edges': <String, String?>{'success': 'build', 'error': '#'},
},
<String, dynamic>{
'key': 'build',
'type': 'model',
'edges': <String, String?>{'success': 'audit', 'error': '#'},
},
<String, dynamic>{
'key': 'audit',
'type': 'model',
'edges': <String, String?>{'success': '#success'},
},
],
},
'steps': <dynamic>[
<String, dynamic>{
'stage': 'plan',
'sequence': 5,
'status': 'completed',
'outcome': 'success',
},
<String, dynamic>{
'stage': 'build',
'sequence': 2,
'status': 'completed',
'outcome': 'success',
},
<String, dynamic>{
'stage': 'plan',
'sequence': 1,
'status': 'completed',
'outcome': 'success',
},
],
};
Future<void> 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<JsonMap>.broadcast();
final listRequests = <Completer<JsonMap>>[];
final detailRequests = <Completer<JsonMap>>[];
@override
Stream<JsonMap> get frames => _frames.stream;
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) {
final request = Completer<JsonMap>();
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<RunGraphView>(
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);
});
}