Files
pipelines/app/test/features/walkthrough/walkthrough_gate_test.dart
T
alan 30ba70ade8 Add first-run walkthrough
Guide new users through connecting a server, configuring an agent harness, starting runs, and chatting with agents. Persist completion per device and offer the walkthrough again for empty servers or from Settings, with widget coverage and implementation notes.
2026-11-12 02:23:15 +00:00

342 lines
11 KiB
Dart

import 'dart:async';
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/walkthrough/walkthrough_gate.dart';
import 'package:pipelines_app/features/walkthrough/walkthrough_store.dart';
import 'package:pipelines_app/ui/theme/app_theme.dart';
import 'package:shared_preferences/shared_preferences.dart';
const _welcome = 'Welcome to Pipelines';
Future<SharedPreferences?> _noPreferences() async => null;
/// A gateway that answers the three empty-server list calls from fixed lists.
class _FakeGateway implements ApiGateway {
_FakeGateway({this.runs = const <Object>[], this.failing = false});
/// Runs the server reports; pipelines and chats are always empty here.
final List<Object> runs;
bool failing;
final calls = <String>[];
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) async {
calls.add(type);
if (failing) throw StateError('offline');
return switch (type) {
'list_pipelines' => <String, dynamic>{'pipelines': const <Object>[]},
'list_runs' => <String, dynamic>{'runs': runs},
'chat_sessions' => <String, dynamic>{'chat_sessions': const <Object>[]},
_ => <String, dynamic>{'type': 'error'},
};
}
@override
Stream<JsonMap> get frames => const Stream<JsonMap>.empty();
}
/// Delegates to [inner], but holds [isSeen] until [release] so a test can
/// change the page visibility while an offer is still in flight.
class _HeldStore implements WalkthroughStore {
_HeldStore(this.inner);
final MemoryWalkthroughStore inner;
Completer<void>? _gate;
void hold() => _gate = Completer<void>();
void release() {
_gate?.complete();
_gate = null;
}
@override
Future<bool> isSeen() async {
await _gate?.future;
return inner.isSeen();
}
@override
Future<void> markSeen() => inner.markSeen();
@override
Future<bool> wasOffered(String serverScope) =>
inner.wasOffered(serverScope);
@override
Future<void> markOffered(String serverScope) =>
inner.markOffered(serverScope);
}
/// [link] stands in for the session: its value is whether the server connected,
/// and notifying it is the connection transition. Defaults to connected.
Widget _host({
required WalkthroughStore store,
ApiGateway? gateway,
bool enabled = true,
ValueNotifier<bool>? link,
}) {
final session = link ?? ValueNotifier<bool>(true);
return MaterialApp(
theme: appLightTheme(),
darkTheme: appDarkTheme(),
home: Scaffold(
body: FirstRunWalkthroughGate(
store: store,
enabled: enabled,
serverScope: 'server-a',
connection: session,
connected: () => session.value,
gateway: gateway,
child: const Text('Pipelines page'),
),
),
);
}
Future<void> _finishWalkthrough(WidgetTester tester) async {
for (var page = 0; page < 3; page++) {
await tester.tap(find.byKey(const ValueKey<String>('walkthrough.next')));
await tester.pumpAndSettle();
}
await tester.tap(find.text('Done'));
await tester.pumpAndSettle();
}
void main() {
testWidgets('first launch shows the walkthrough once per device', (
tester,
) async {
final store = MemoryWalkthroughStore();
await tester.pumpWidget(_host(store: store));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsOneWidget);
await _finishWalkthrough(tester);
expect(find.text(_welcome), findsNothing);
expect(store.seen, isTrue);
// A later launch on the same device does not show it again.
await tester.pumpWidget(const SizedBox());
await tester.pumpWidget(_host(store: store));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(find.text('Pipelines page'), findsOneWidget);
});
testWidgets('Done persists the seen record and no server query runs', (
tester,
) async {
final store = MemoryWalkthroughStore();
final gateway = _FakeGateway();
await tester.pumpWidget(_host(store: store, gateway: gateway));
await tester.pumpAndSettle();
await _finishWalkthrough(tester);
expect(store.seen, isTrue);
expect(
gateway.calls,
isEmpty,
reason: 'first launch needs no server check',
);
});
testWidgets('Skip on the first page persists the seen record', (
tester,
) async {
final store = MemoryWalkthroughStore();
await tester.pumpWidget(_host(store: store));
await tester.pumpAndSettle();
await tester.tap(find.byKey(const ValueKey<String>('walkthrough.skip')));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(store.seen, isTrue);
});
testWidgets('a seen device on an empty server is offered it once', (
tester,
) async {
final store = MemoryWalkthroughStore(seen: true);
final gateway = _FakeGateway();
await tester.pumpWidget(_host(store: store, gateway: gateway));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsOneWidget);
expect(store.offered, {'server-a'});
expect(
gateway.calls,
containsAll(['list_pipelines', 'list_runs', 'chat_sessions']),
);
await tester.tap(find.byKey(const ValueKey<String>('walkthrough.skip')));
await tester.pumpAndSettle();
// The server was offered already, so a fresh mount stays quiet.
await tester.pumpWidget(const SizedBox());
await tester.pumpWidget(_host(store: store, gateway: gateway));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
});
testWidgets(
'a seen device that starts disconnected is offered once it connects',
(tester) async {
// Startup order in the app: the Pipelines page mounts before the session
// has connected. The server must not be asked yet, and the offer must
// still happen after the connection arrives.
final store = MemoryWalkthroughStore(seen: true);
final gateway = _FakeGateway();
final link = ValueNotifier<bool>(false);
await tester.pumpWidget(
_host(store: store, gateway: gateway, link: link),
);
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(
gateway.calls,
isEmpty,
reason: 'no server call while disconnected',
);
expect(store.offered, isEmpty);
link.value = true;
await tester.pumpAndSettle();
expect(find.text(_welcome), findsOneWidget);
expect(store.offered, {'server-a'});
expect(
gateway.calls,
containsAll(['list_pipelines', 'list_runs', 'chat_sessions']),
);
},
);
testWidgets('an unreadable check is retried on the next connection', (
tester,
) async {
final store = MemoryWalkthroughStore(seen: true);
final gateway = _FakeGateway(failing: true);
final link = ValueNotifier<bool>(true);
await tester.pumpWidget(_host(store: store, gateway: gateway, link: link));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(store.offered, isEmpty);
final callsAfterFailure = gateway.calls.length;
// A repeated notification while still connected does not re-query.
link.notifyListeners();
await tester.pumpAndSettle();
expect(gateway.calls.length, callsAfterFailure);
// The server recovers; a fresh connection runs the check and offers it.
gateway.failing = false;
link.value = false;
await tester.pumpAndSettle();
link.value = true;
await tester.pumpAndSettle();
expect(find.text(_welcome), findsOneWidget);
expect(store.offered, {'server-a'});
});
testWidgets('a seen device on a server with work is not offered', (
tester,
) async {
final store = MemoryWalkthroughStore(seen: true);
final gateway = _FakeGateway(
runs: <Object>[
<String, dynamic>{'id': 'run-1'},
],
);
await tester.pumpWidget(_host(store: store, gateway: gateway));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(store.offered, isEmpty);
});
testWidgets('an unreadable server never triggers the walkthrough', (
tester,
) async {
final store = MemoryWalkthroughStore(seen: true);
await tester.pumpWidget(
_host(store: store, gateway: _FakeGateway(failing: true)),
);
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(store.offered, isEmpty);
});
testWidgets('the Pipelines page being hidden defers the check', (
tester,
) async {
final store = MemoryWalkthroughStore();
await tester.pumpWidget(_host(store: store, enabled: false));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(store.seen, isFalse);
await tester.pumpWidget(_host(store: store, enabled: true));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsOneWidget);
});
testWidgets(
'hiding Pipelines while an offer is pending keeps the walkthrough closed',
(tester) async {
final inner = MemoryWalkthroughStore();
final store = _HeldStore(inner)..hold();
await tester.pumpWidget(_host(store: store));
await tester.pump();
// The Pipelines page is hidden while the offer is still reading the store.
await tester.pumpWidget(_host(store: store, enabled: false));
store.release();
await tester.pumpAndSettle();
expect(find.text(_welcome), findsNothing);
expect(inner.seen, isFalse);
// Showing Pipelines again offers it once, on the same mount.
await tester.pumpWidget(_host(store: store, enabled: true));
await tester.pumpAndSettle();
expect(find.text(_welcome), findsOneWidget);
},
);
test('an unavailable preference store reports seen and offered', () async {
// The opener yields no preferences, as when the platform store is absent:
// every read reports "seen" and every write is quietly dropped.
const store = SharedPreferencesWalkthroughStore(open: _noPreferences);
expect(await store.isSeen(), isTrue);
expect(await store.wasOffered('server-a'), isTrue);
await store.markSeen();
await store.markOffered('server-a');
expect(await store.isSeen(), isTrue);
});
test(
'SharedPreferences store records seen and offered under the keys',
() async {
SharedPreferences.setMockInitialValues(<String, Object>{});
const store = SharedPreferencesWalkthroughStore();
expect(await store.isSeen(), isFalse);
await store.markSeen();
expect(await store.isSeen(), isTrue);
expect(await store.wasOffered('server-a'), isFalse);
await store.markOffered('server-a');
expect(await store.wasOffered('server-a'), isTrue);
expect(await store.wasOffered('server-b'), isFalse);
},
);
}