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.
This commit is contained in:
@@ -28,6 +28,8 @@ import '../features/runs/ui/run_search_selection.dart';
|
||||
import '../features/search/domain/search_target.dart';
|
||||
import '../features/settings/settings_screen.dart';
|
||||
import '../features/settings/settings_store.dart';
|
||||
import '../features/walkthrough/walkthrough_gate.dart';
|
||||
import '../features/walkthrough/walkthrough_store.dart';
|
||||
import '../features/updates/app_updates.dart';
|
||||
import '../features/updates/launch_update.dart';
|
||||
import '../features/updates/launch_update_dialog.dart';
|
||||
@@ -579,6 +581,10 @@ class _PipelinesAppState extends State<PipelinesApp>
|
||||
_attentionCount.value = count;
|
||||
}
|
||||
|
||||
/// The device's first-run walkthrough record (per device, not per server).
|
||||
final WalkthroughStore _walkthroughStore =
|
||||
const SharedPreferencesWalkthroughStore();
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) => widget.servers == null
|
||||
? MyApp.router(routerConfig: _config)
|
||||
@@ -837,32 +843,40 @@ class _PipelinesAppState extends State<PipelinesApp>
|
||||
_bodyRoutes[AppDestination.pipelines] ?? AppRoute.pipelines,
|
||||
),
|
||||
destinationBodies: {
|
||||
AppDestination.pipelines: (_) => PipelinesDestination(
|
||||
session: _session,
|
||||
server: widget.server,
|
||||
active: _destinationOf(route.kind) == AppDestination.pipelines,
|
||||
legacyPendingEndpoints: widget.legacyPendingEndpoints,
|
||||
refreshToken: _pipelinesRefresh,
|
||||
onRunStarted: _runStarted,
|
||||
onViewPipelineRuns: (id) =>
|
||||
_delegate.goTo(AppRoute.runsForPipeline(id)),
|
||||
onOpenSchedules: _delegate.openSchedules,
|
||||
onOpenSettings: () => _delegate.goTo(AppRoute.settings),
|
||||
// The open pipeline is part of the route, so Back steps out of it.
|
||||
onSelectionChanged: (id) {
|
||||
final current = _delegate.route;
|
||||
if (current.kind != AppRouteKind.pipelines) return;
|
||||
if (id == null) {
|
||||
if (current.pipelineId != null) {
|
||||
_delegate.goTo(AppRoute.pipelines);
|
||||
AppDestination.pipelines: (_) => FirstRunWalkthroughGate(
|
||||
store: _walkthroughStore,
|
||||
enabled: _destinationOf(route.kind) == AppDestination.pipelines,
|
||||
serverScope: _navigationScope,
|
||||
connection: _session,
|
||||
connected: () => _session.connected,
|
||||
gateway: _session.client,
|
||||
child: PipelinesDestination(
|
||||
session: _session,
|
||||
server: widget.server,
|
||||
active: _destinationOf(route.kind) == AppDestination.pipelines,
|
||||
legacyPendingEndpoints: widget.legacyPendingEndpoints,
|
||||
refreshToken: _pipelinesRefresh,
|
||||
onRunStarted: _runStarted,
|
||||
onViewPipelineRuns: (id) =>
|
||||
_delegate.goTo(AppRoute.runsForPipeline(id)),
|
||||
onOpenSchedules: _delegate.openSchedules,
|
||||
onOpenSettings: () => _delegate.goTo(AppRoute.settings),
|
||||
// The open pipeline is part of the route, so Back steps out of it.
|
||||
onSelectionChanged: (id) {
|
||||
final current = _delegate.route;
|
||||
if (current.kind != AppRouteKind.pipelines) return;
|
||||
if (id == null) {
|
||||
if (current.pipelineId != null) {
|
||||
_delegate.goTo(AppRoute.pipelines);
|
||||
}
|
||||
} else if (current.pipelineId != id) {
|
||||
_delegate.goTo(AppRoute.pipeline(id));
|
||||
}
|
||||
} else if (current.pipelineId != id) {
|
||||
_delegate.goTo(AppRoute.pipeline(id));
|
||||
}
|
||||
},
|
||||
initialPipelineId: pipelinesRoute.pipelineId,
|
||||
initialVersion: pipelinesRoute.version,
|
||||
initialStageKey: pipelinesRoute.stageKey,
|
||||
},
|
||||
initialPipelineId: pipelinesRoute.pipelineId,
|
||||
initialVersion: pipelinesRoute.version,
|
||||
initialStageKey: pipelinesRoute.stageKey,
|
||||
),
|
||||
),
|
||||
// The one place a field or artifact hit's selection can be resolved: the
|
||||
// run detail owns the recorded visit and Summary section.
|
||||
|
||||
@@ -13,4 +13,5 @@ abstract final class SettingsKeys {
|
||||
static const keyboardShortcuts = ValueKey<String>(
|
||||
'settings.keyboardShortcuts',
|
||||
);
|
||||
static const walkthrough = ValueKey<String>('settings.walkthrough');
|
||||
}
|
||||
|
||||
@@ -37,6 +37,7 @@ import 'server_connections.dart';
|
||||
import 'saved_servers_section.dart';
|
||||
import 'managed_connection_section.dart';
|
||||
import 'settings_keyboard_shortcuts_section.dart';
|
||||
import 'settings_walkthrough_section.dart';
|
||||
|
||||
part 'settings_topic_pages.dart';
|
||||
|
||||
|
||||
@@ -85,7 +85,10 @@ extension _SettingsTopicPages on _SettingsScreenState {
|
||||
SettingsGroup(
|
||||
title: 'Help',
|
||||
leadingRows: true,
|
||||
children: const [SettingsKeyboardShortcutsSection()],
|
||||
children: const [
|
||||
SettingsKeyboardShortcutsSection(),
|
||||
SettingsWalkthroughSection(),
|
||||
],
|
||||
),
|
||||
if (widget.onOpenSchedules case final open?)
|
||||
SettingsGroup(
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
import 'package:flutter/material.dart';
|
||||
|
||||
import '../walkthrough/first_run_walkthrough.dart';
|
||||
import 'settings_keys.dart';
|
||||
import 'settings_row.dart';
|
||||
|
||||
/// Reopens the first-run walkthrough. It only shows the walkthrough; it never
|
||||
/// changes the device's seen record.
|
||||
class SettingsWalkthroughSection extends StatelessWidget {
|
||||
const SettingsWalkthroughSection({super.key});
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) => SettingsRow(
|
||||
key: SettingsKeys.walkthrough,
|
||||
leading: const Icon(Icons.school_outlined),
|
||||
title: const Text('Show the walkthrough'),
|
||||
subtitle: const Text(
|
||||
'Four short steps: connect, set up an agent, run, chat.',
|
||||
),
|
||||
chevron: true,
|
||||
onTap: () => showFirstRunWalkthrough(context),
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,183 @@
|
||||
import 'package:flutter/material.dart';
|
||||
|
||||
import '../../ui/adaptive/app_popups.dart';
|
||||
import 'walkthrough_harness_command.dart';
|
||||
import 'walkthrough_steps.dart';
|
||||
|
||||
/// Opens the walkthrough as a Material details sheet on phones and a dialog on
|
||||
/// wide windows. [onClosed] runs once however it closes (Skip, Done, the close
|
||||
/// button or a tap outside), so the caller can record it as seen.
|
||||
Future<void> showFirstRunWalkthrough(
|
||||
BuildContext context, {
|
||||
Future<void> Function()? onClosed,
|
||||
}) async {
|
||||
await showAppDetails<void>(
|
||||
context,
|
||||
maxWidth: 560,
|
||||
builder: (sheet) =>
|
||||
FirstRunWalkthrough(onClose: () => Navigator.of(sheet).pop()),
|
||||
);
|
||||
await onClosed?.call();
|
||||
}
|
||||
|
||||
/// The four-page stepper: Back and Next between pages, Skip on every page and
|
||||
/// Done on the last. Every control is a standard Material button; the layout
|
||||
/// wraps rather than clipping at large text scales.
|
||||
class FirstRunWalkthrough extends StatefulWidget {
|
||||
const FirstRunWalkthrough({
|
||||
super.key,
|
||||
required this.onClose,
|
||||
this.steps = walkthroughSteps,
|
||||
});
|
||||
|
||||
/// Called by Skip, Done and the close button.
|
||||
final VoidCallback onClose;
|
||||
final List<WalkthroughStep> steps;
|
||||
|
||||
@override
|
||||
State<FirstRunWalkthrough> createState() => _FirstRunWalkthroughState();
|
||||
}
|
||||
|
||||
class _FirstRunWalkthroughState extends State<FirstRunWalkthrough> {
|
||||
int _index = 0;
|
||||
|
||||
bool get _last => _index == widget.steps.length - 1;
|
||||
|
||||
void _back() => setState(() => _index = _index > 0 ? _index - 1 : 0);
|
||||
|
||||
void _next() => setState(() => _index = _last ? _index : _index + 1);
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
final step = widget.steps[_index];
|
||||
final theme = Theme.of(context);
|
||||
final content = Semantics(
|
||||
scopesRoute: true,
|
||||
namesRoute: true,
|
||||
explicitChildNodes: true,
|
||||
label: 'Pipelines walkthrough',
|
||||
child: Padding(
|
||||
padding: const EdgeInsets.fromLTRB(24, 8, 24, 24),
|
||||
child: Column(
|
||||
mainAxisSize: MainAxisSize.min,
|
||||
crossAxisAlignment: CrossAxisAlignment.stretch,
|
||||
children: <Widget>[
|
||||
Text(
|
||||
'Step ${_index + 1} of ${widget.steps.length}',
|
||||
key: const ValueKey<String>('walkthrough.progress'),
|
||||
style: theme.textTheme.labelLarge,
|
||||
),
|
||||
const SizedBox(height: 8),
|
||||
LinearProgressIndicator(value: (_index + 1) / widget.steps.length),
|
||||
const SizedBox(height: 20),
|
||||
Row(
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: <Widget>[
|
||||
Icon(step.icon, color: theme.colorScheme.primary),
|
||||
const SizedBox(width: 12),
|
||||
Expanded(
|
||||
child: Text(
|
||||
step.title,
|
||||
key: ValueKey<String>('walkthrough.title.$_index'),
|
||||
style: theme.textTheme.headlineSmall,
|
||||
),
|
||||
),
|
||||
],
|
||||
),
|
||||
const SizedBox(height: 12),
|
||||
Text(step.body, style: theme.textTheme.bodyLarge),
|
||||
for (final point in step.points) ...<Widget>[
|
||||
const SizedBox(height: 8),
|
||||
_Point(text: point),
|
||||
],
|
||||
if (step.showsHarnessCommand) ...<Widget>[
|
||||
const SizedBox(height: 16),
|
||||
const WalkthroughHarnessCommand(),
|
||||
],
|
||||
const SizedBox(height: 24),
|
||||
_Footer(
|
||||
last: _last,
|
||||
canGoBack: _index > 0,
|
||||
onBack: _back,
|
||||
onNext: _last ? widget.onClose : _next,
|
||||
onSkip: widget.onClose,
|
||||
),
|
||||
],
|
||||
),
|
||||
),
|
||||
);
|
||||
// A wide window wraps the sheet's content in its own scroll view; a phone
|
||||
// sheet does not, so the page scrolls here at large text scales.
|
||||
return usesDesktopPopups(context)
|
||||
? content
|
||||
: SingleChildScrollView(child: content);
|
||||
}
|
||||
}
|
||||
|
||||
class _Point extends StatelessWidget {
|
||||
const _Point({required this.text});
|
||||
|
||||
final String text;
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) => Row(
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: <Widget>[
|
||||
const Padding(
|
||||
padding: EdgeInsets.only(top: 2),
|
||||
child: Icon(Icons.circle, size: 6),
|
||||
),
|
||||
const SizedBox(width: 12),
|
||||
Expanded(
|
||||
child: Text(text, style: Theme.of(context).textTheme.bodyMedium),
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
class _Footer extends StatelessWidget {
|
||||
const _Footer({
|
||||
required this.last,
|
||||
required this.canGoBack,
|
||||
required this.onBack,
|
||||
required this.onNext,
|
||||
required this.onSkip,
|
||||
});
|
||||
|
||||
final bool last;
|
||||
final bool canGoBack;
|
||||
final VoidCallback onBack;
|
||||
final VoidCallback onNext;
|
||||
final VoidCallback onSkip;
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) => Wrap(
|
||||
alignment: WrapAlignment.spaceBetween,
|
||||
crossAxisAlignment: WrapCrossAlignment.center,
|
||||
spacing: 8,
|
||||
runSpacing: 8,
|
||||
children: <Widget>[
|
||||
TextButton(
|
||||
key: const ValueKey<String>('walkthrough.skip'),
|
||||
onPressed: onSkip,
|
||||
child: const Text('Skip'),
|
||||
),
|
||||
Wrap(
|
||||
spacing: 8,
|
||||
runSpacing: 8,
|
||||
children: <Widget>[
|
||||
TextButton(
|
||||
key: const ValueKey<String>('walkthrough.back'),
|
||||
onPressed: canGoBack ? onBack : null,
|
||||
child: const Text('Back'),
|
||||
),
|
||||
FilledButton(
|
||||
key: const ValueKey<String>('walkthrough.next'),
|
||||
onPressed: onNext,
|
||||
child: Text(last ? 'Done' : 'Next'),
|
||||
),
|
||||
],
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,200 @@
|
||||
import 'dart:async';
|
||||
|
||||
import 'package:flutter/widgets.dart';
|
||||
|
||||
import '../../core/api_gateway.dart';
|
||||
import 'first_run_walkthrough.dart';
|
||||
import 'walkthrough_store.dart';
|
||||
|
||||
/// Reports whether the server has no pipelines, runs or chats yet. Returns null
|
||||
/// when any of the three lists cannot be read, so an unreadable server never
|
||||
/// triggers the walkthrough.
|
||||
Future<bool?> serverHasNoWorkYet(ApiGateway? gateway) async {
|
||||
if (gateway == null) return null;
|
||||
try {
|
||||
final replies = await Future.wait(<Future<JsonMap>>[
|
||||
gateway.call('list_pipelines', {'include_archived': true}),
|
||||
gateway.call('list_runs'),
|
||||
gateway.call('chat_sessions'),
|
||||
]);
|
||||
final lists = <Object?>[
|
||||
replies[0]['pipelines'],
|
||||
replies[1]['runs'],
|
||||
replies[2]['chat_sessions'],
|
||||
];
|
||||
if (lists.any((list) => list is! List)) return null;
|
||||
return lists.every((list) => (list as List).isEmpty);
|
||||
} catch (_) {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/// Offers the walkthrough from the Pipelines page, which is the first screen a
|
||||
/// new user sees. It is offered when:
|
||||
///
|
||||
/// * the device has not finished or skipped it yet (first launch, once); or
|
||||
/// * the device already has, and the connected server has no pipelines, runs
|
||||
/// or chats, and that server has not been offered it before.
|
||||
///
|
||||
/// The server check needs a connected session. While disconnected it waits, and
|
||||
/// it runs again on each new connection until the server answers. A check that
|
||||
/// cannot read the server leaves the gate open to retry; a decided check (the
|
||||
/// walkthrough shown, or the server has work) ends it for this mount.
|
||||
///
|
||||
/// Nothing is shown while the store cannot be read, because an unavailable
|
||||
/// store reports "seen". The check runs only while [enabled] (the Pipelines tab
|
||||
/// is the one showing).
|
||||
class FirstRunWalkthroughGate extends StatefulWidget {
|
||||
const FirstRunWalkthroughGate({
|
||||
super.key,
|
||||
required this.child,
|
||||
required this.store,
|
||||
required this.enabled,
|
||||
required this.serverScope,
|
||||
required this.connection,
|
||||
required this.connected,
|
||||
this.gateway,
|
||||
});
|
||||
|
||||
final Widget child;
|
||||
final WalkthroughStore store;
|
||||
|
||||
/// Whether the Pipelines page is the one showing.
|
||||
final bool enabled;
|
||||
|
||||
/// The connected server's scope, recorded when the walkthrough is offered.
|
||||
final String serverScope;
|
||||
|
||||
/// Notifies when the connection may have changed; the gate re-reads
|
||||
/// [connected] on each notification.
|
||||
final Listenable connection;
|
||||
|
||||
/// Whether the server session is connected right now.
|
||||
final bool Function() connected;
|
||||
|
||||
/// The connected server's gateway, used for the empty-server check.
|
||||
final ApiGateway? gateway;
|
||||
|
||||
@override
|
||||
State<FirstRunWalkthroughGate> createState() =>
|
||||
_FirstRunWalkthroughGateState();
|
||||
}
|
||||
|
||||
class _FirstRunWalkthroughGateState extends State<FirstRunWalkthroughGate> {
|
||||
/// The offer is decided for this mount: shown, or nothing left to offer.
|
||||
bool _decided = false;
|
||||
|
||||
/// An offer is in flight.
|
||||
bool _running = false;
|
||||
|
||||
/// A new connection arrived while an offer was in flight.
|
||||
bool _connectedAgain = false;
|
||||
late bool _wasConnected;
|
||||
|
||||
@override
|
||||
void initState() {
|
||||
super.initState();
|
||||
_wasConnected = widget.connected();
|
||||
widget.connection.addListener(_onConnectionChanged);
|
||||
_scheduleIfEnabled();
|
||||
}
|
||||
|
||||
@override
|
||||
void didUpdateWidget(FirstRunWalkthroughGate oldWidget) {
|
||||
super.didUpdateWidget(oldWidget);
|
||||
if (oldWidget.connection != widget.connection) {
|
||||
oldWidget.connection.removeListener(_onConnectionChanged);
|
||||
widget.connection.addListener(_onConnectionChanged);
|
||||
}
|
||||
_scheduleIfEnabled();
|
||||
}
|
||||
|
||||
@override
|
||||
void dispose() {
|
||||
widget.connection.removeListener(_onConnectionChanged);
|
||||
super.dispose();
|
||||
}
|
||||
|
||||
/// Acts only on a disconnected-to-connected transition, so frequent session
|
||||
/// notifications while connected never repeat the server check.
|
||||
void _onConnectionChanged() {
|
||||
final connected = widget.connected();
|
||||
final became = connected && !_wasConnected;
|
||||
_wasConnected = connected;
|
||||
if (!became || _decided) return;
|
||||
if (_running) {
|
||||
_connectedAgain = true;
|
||||
return;
|
||||
}
|
||||
_scheduleIfEnabled();
|
||||
}
|
||||
|
||||
void _scheduleIfEnabled() {
|
||||
if (_decided || _running || !widget.enabled) return;
|
||||
_running = true;
|
||||
// A connection can arrive between frames; the post-frame callback needs a
|
||||
// frame, so request one explicitly.
|
||||
WidgetsBinding.instance.addPostFrameCallback((_) {
|
||||
if (!_active) {
|
||||
// Pipelines is hidden (or the gate is gone): release the flag so a
|
||||
// later enable reschedules the offer through didUpdateWidget.
|
||||
_running = false;
|
||||
return;
|
||||
}
|
||||
unawaited(_runOffer());
|
||||
});
|
||||
WidgetsBinding.instance.ensureVisualUpdate();
|
||||
}
|
||||
|
||||
/// The gate may offer only while mounted and while the Pipelines page is the
|
||||
/// one showing. Checked after every await and before every show.
|
||||
bool get _active => mounted && widget.enabled;
|
||||
|
||||
Future<void> _runOffer() async {
|
||||
try {
|
||||
await _offer();
|
||||
} finally {
|
||||
_running = false;
|
||||
final again = _connectedAgain;
|
||||
_connectedAgain = false;
|
||||
if (again && !_decided) _scheduleIfEnabled();
|
||||
}
|
||||
}
|
||||
|
||||
Future<void> _offer() async {
|
||||
final seen = await widget.store.isSeen();
|
||||
if (!_active) return;
|
||||
if (!seen) {
|
||||
_decided = true;
|
||||
await _showIfActive();
|
||||
return;
|
||||
}
|
||||
if (await widget.store.wasOffered(widget.serverScope)) {
|
||||
if (!_active) return;
|
||||
_decided = true;
|
||||
return;
|
||||
}
|
||||
// Wait for a connection; the connection listener runs the check again.
|
||||
if (!widget.connected()) return;
|
||||
final empty = await serverHasNoWorkYet(widget.gateway);
|
||||
if (!_active) return;
|
||||
// Unreadable: stay open so the next connection retries the check.
|
||||
if (empty == null) return;
|
||||
_decided = true;
|
||||
if (!empty) return;
|
||||
await widget.store.markOffered(widget.serverScope);
|
||||
await _showIfActive();
|
||||
}
|
||||
|
||||
Future<void> _showIfActive() async {
|
||||
if (!_active) return;
|
||||
await _show();
|
||||
}
|
||||
|
||||
Future<void> _show() async {
|
||||
await showFirstRunWalkthrough(context, onClosed: widget.store.markSeen);
|
||||
}
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) => widget.child;
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:flutter/services.dart';
|
||||
|
||||
import 'walkthrough_steps.dart';
|
||||
|
||||
/// The harness page's command: an agent picker and the one command it selects,
|
||||
/// with a single copy button for that command.
|
||||
class WalkthroughHarnessCommand extends StatefulWidget {
|
||||
const WalkthroughHarnessCommand({super.key});
|
||||
|
||||
@override
|
||||
State<WalkthroughHarnessCommand> createState() =>
|
||||
_WalkthroughHarnessCommandState();
|
||||
}
|
||||
|
||||
class _WalkthroughHarnessCommandState extends State<WalkthroughHarnessCommand> {
|
||||
String _agent = harnessAgents.first;
|
||||
bool _copied = false;
|
||||
|
||||
Future<void> _copy(String command) async {
|
||||
try {
|
||||
await Clipboard.setData(ClipboardData(text: command));
|
||||
} catch (_) {
|
||||
// The command stays selectable, so a failed copy never claims success.
|
||||
return;
|
||||
}
|
||||
if (!mounted) return;
|
||||
setState(() => _copied = true);
|
||||
}
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
final scheme = Theme.of(context).colorScheme;
|
||||
final command = harnessSetupCommand(_agent);
|
||||
return Column(
|
||||
crossAxisAlignment: CrossAxisAlignment.stretch,
|
||||
children: <Widget>[
|
||||
Text('Agent', style: Theme.of(context).textTheme.labelLarge),
|
||||
const SizedBox(height: 8),
|
||||
Wrap(
|
||||
spacing: 8,
|
||||
runSpacing: 8,
|
||||
children: <Widget>[
|
||||
for (final agent in harnessAgents)
|
||||
ChoiceChip(
|
||||
key: ValueKey<String>('walkthrough.agent.$agent'),
|
||||
label: Text(agent),
|
||||
selected: agent == _agent,
|
||||
onSelected: (_) => setState(() {
|
||||
_agent = agent;
|
||||
_copied = false;
|
||||
}),
|
||||
),
|
||||
],
|
||||
),
|
||||
const SizedBox(height: 12),
|
||||
DecoratedBox(
|
||||
decoration: BoxDecoration(
|
||||
color: scheme.surfaceContainerHighest,
|
||||
borderRadius: BorderRadius.circular(12),
|
||||
),
|
||||
child: Padding(
|
||||
padding: const EdgeInsets.only(left: 12, right: 4),
|
||||
child: Row(
|
||||
children: <Widget>[
|
||||
Expanded(
|
||||
child: SelectableText(
|
||||
command,
|
||||
key: const ValueKey<String>('walkthrough.command'),
|
||||
style: Theme.of(context).textTheme.bodyLarge,
|
||||
),
|
||||
),
|
||||
IconButton(
|
||||
key: const ValueKey<String>('walkthrough.copy'),
|
||||
tooltip: _copied ? 'Command copied' : 'Copy command',
|
||||
onPressed: () => _copy(command),
|
||||
icon: Icon(_copied ? Icons.check : Icons.copy_outlined),
|
||||
),
|
||||
],
|
||||
),
|
||||
),
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
import 'package:flutter/material.dart';
|
||||
|
||||
/// One page of the first-run walkthrough. Pure content: no widgets, so the
|
||||
/// copy can be checked without pumping a tree.
|
||||
class WalkthroughStep {
|
||||
const WalkthroughStep({
|
||||
required this.icon,
|
||||
required this.title,
|
||||
required this.body,
|
||||
this.points = const <String>[],
|
||||
this.showsHarnessCommand = false,
|
||||
});
|
||||
|
||||
final IconData icon;
|
||||
final String title;
|
||||
final String body;
|
||||
|
||||
/// Short labelled facts shown under the body, one per line.
|
||||
final List<String> points;
|
||||
|
||||
/// Whether this page shows the harness setup command picker.
|
||||
final bool showsHarnessCommand;
|
||||
}
|
||||
|
||||
/// The agents `pipelines harness setup` accepts, in the order they are offered.
|
||||
const harnessAgents = <String>['claude', 'codex', 'opencode', 'pi'];
|
||||
|
||||
/// The command for [agent], exactly as a terminal should run it.
|
||||
String harnessSetupCommand(String agent) => 'pipelines harness setup $agent';
|
||||
|
||||
/// The four walkthrough pages, in order.
|
||||
const walkthroughSteps = <WalkthroughStep>[
|
||||
WalkthroughStep(
|
||||
icon: Icons.hub_outlined,
|
||||
title: 'Welcome to Pipelines',
|
||||
body:
|
||||
'Pipelines runs reusable AI workflows and holds chats with coding '
|
||||
'agents. Both live on your server, so start by connecting this app '
|
||||
'to it.',
|
||||
points: <String>[
|
||||
'Pipelines: workflows you define once and run again.',
|
||||
'Chats: conversations with coding agents on the server.',
|
||||
'Connect: open Settings, then Connection, enter the Server URL and '
|
||||
'choose Connect.',
|
||||
],
|
||||
),
|
||||
WalkthroughStep(
|
||||
icon: Icons.build_circle_outlined,
|
||||
title: 'Set up an agent harness',
|
||||
body:
|
||||
'A harness lets Pipelines drive a coding agent. Choose the agent you '
|
||||
'use, then run its setup command in a terminal.',
|
||||
showsHarnessCommand: true,
|
||||
),
|
||||
WalkthroughStep(
|
||||
icon: Icons.play_circle_outline,
|
||||
title: 'Start a run',
|
||||
body:
|
||||
'Pipelines shows your workflows. Runs shows every run with its '
|
||||
'progress and results.',
|
||||
points: <String>[
|
||||
'Pipelines tab: open a workflow and fill in its inputs.',
|
||||
'Runs tab: follow a run as it works, then read what it produced.',
|
||||
'Choose Run on a workflow to start one.',
|
||||
],
|
||||
),
|
||||
WalkthroughStep(
|
||||
icon: Icons.forum_outlined,
|
||||
title: 'Chat with an agent',
|
||||
body:
|
||||
'The Chat tab lists your conversations. Open one to read the thread '
|
||||
'and reply.',
|
||||
points: <String>[
|
||||
'Float: pop a chat into its own window while you work elsewhere.',
|
||||
'Terminal: open a terminal beside the Chat tab for direct commands.',
|
||||
'New chat starts a conversation with an agent.',
|
||||
],
|
||||
),
|
||||
];
|
||||
@@ -0,0 +1,118 @@
|
||||
import 'package:shared_preferences/shared_preferences.dart';
|
||||
|
||||
/// The device-level key for "the first-run walkthrough was finished or skipped".
|
||||
/// It is per device, not per server, so a new server never repeats it.
|
||||
const String walkthroughSeenKey = 'pipelines.next.firstRunWalkthrough.v1';
|
||||
|
||||
/// The key listing the server scopes that were already offered the walkthrough
|
||||
/// because they had no pipelines, runs or chats yet.
|
||||
const String walkthroughOfferedKey = 'pipelines.next.walkthroughOffered.v1';
|
||||
|
||||
/// The persistence seam for the walkthrough. A store that cannot be read or
|
||||
/// written reports "seen" and "offered", so an unavailable store never nags.
|
||||
abstract interface class WalkthroughStore {
|
||||
Future<bool> isSeen();
|
||||
|
||||
Future<void> markSeen();
|
||||
|
||||
Future<bool> wasOffered(String serverScope);
|
||||
|
||||
Future<void> markOffered(String serverScope);
|
||||
}
|
||||
|
||||
Future<SharedPreferences?> _openPreferences() async {
|
||||
try {
|
||||
return await SharedPreferences.getInstance();
|
||||
} catch (_) {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/// `shared_preferences`-backed storage under the `pipelines.next` keys.
|
||||
///
|
||||
/// [open] is the seam for an unavailable platform store (tests pass one that
|
||||
/// yields null); production opens the real preferences.
|
||||
class SharedPreferencesWalkthroughStore implements WalkthroughStore {
|
||||
const SharedPreferencesWalkthroughStore({this.open = _openPreferences});
|
||||
|
||||
final Future<SharedPreferences?> Function() open;
|
||||
|
||||
Future<SharedPreferences?> _preferences() => open();
|
||||
|
||||
@override
|
||||
Future<bool> isSeen() async {
|
||||
final preferences = await _preferences();
|
||||
if (preferences == null) return true;
|
||||
try {
|
||||
return preferences.getBool(walkthroughSeenKey) ?? false;
|
||||
} catch (_) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
@override
|
||||
Future<void> markSeen() async {
|
||||
final preferences = await _preferences();
|
||||
if (preferences == null) return;
|
||||
try {
|
||||
await preferences.setBool(walkthroughSeenKey, true);
|
||||
} catch (_) {
|
||||
// Nothing to report: the walkthrough is still dismissed for this run.
|
||||
}
|
||||
}
|
||||
|
||||
@override
|
||||
Future<bool> wasOffered(String serverScope) async {
|
||||
final preferences = await _preferences();
|
||||
if (preferences == null) return true;
|
||||
try {
|
||||
final offered = preferences.getStringList(walkthroughOfferedKey);
|
||||
return offered?.contains(serverScope) ?? false;
|
||||
} catch (_) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
@override
|
||||
Future<void> markOffered(String serverScope) async {
|
||||
final preferences = await _preferences();
|
||||
if (preferences == null) return;
|
||||
try {
|
||||
final offered = <String>{
|
||||
...?preferences.getStringList(walkthroughOfferedKey),
|
||||
serverScope,
|
||||
};
|
||||
await preferences.setStringList(walkthroughOfferedKey, offered.toList());
|
||||
} catch (_) {
|
||||
// A failed write only means the offer may show again later.
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// An in-memory store for tests and previews. It never touches the platform
|
||||
/// store, so a fixture cannot mark a real device as seen.
|
||||
class MemoryWalkthroughStore implements WalkthroughStore {
|
||||
MemoryWalkthroughStore({this.seen = false, Set<String>? offered})
|
||||
: _offered = {...?offered};
|
||||
|
||||
/// Whether the walkthrough is marked seen.
|
||||
bool seen;
|
||||
final Set<String> _offered;
|
||||
|
||||
/// The server scopes already offered the walkthrough.
|
||||
Set<String> get offered => Set.unmodifiable(_offered);
|
||||
|
||||
@override
|
||||
Future<bool> isSeen() async => seen;
|
||||
|
||||
@override
|
||||
Future<void> markSeen() async => seen = true;
|
||||
|
||||
@override
|
||||
Future<bool> wasOffered(String serverScope) async =>
|
||||
_offered.contains(serverScope);
|
||||
|
||||
@override
|
||||
Future<void> markOffered(String serverScope) async =>
|
||||
_offered.add(serverScope);
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
# First-run walkthrough
|
||||
|
||||
A short, skippable four-page walkthrough for new users of the Flutter app.
|
||||
|
||||
## What it does
|
||||
|
||||
- Shows once per device on first launch, from the Pipelines page.
|
||||
- Is also offered once per server when the device has already seen it and the
|
||||
connected server has no pipelines, runs or chats yet (the server is checked
|
||||
with `list_pipelines`, `list_runs` and `chat_sessions`; an unreadable server
|
||||
never triggers it).
|
||||
- Pages: 1) what Pipelines is and how to connect to the server; 2) set up an
|
||||
agent harness, with an agent picker and one copy button for
|
||||
`pipelines harness setup <agent>` (`claude`, `codex`, `opencode`, `pi`);
|
||||
3) the Pipelines and Runs tabs and how to start a run; 4) the Chat tab, float
|
||||
and terminal.
|
||||
- Every page has Skip; Back and Next move between pages; Done ends on the last.
|
||||
- Closing by any route (Skip, Done, the close gesture, a tap outside) records the
|
||||
device as seen.
|
||||
- Settings reopens it from Tools → Help → "Show the walkthrough". Reopening
|
||||
does not change the seen record.
|
||||
|
||||
## Where it lives
|
||||
|
||||
- `lib/features/walkthrough/`
|
||||
- `walkthrough_store.dart`: the seen/offered records (`pipelines.next.*` keys;
|
||||
a store that cannot be read reports "seen", so it never nags).
|
||||
- `walkthrough_steps.dart`: the page copy and agent list (pure data).
|
||||
- `first_run_walkthrough.dart`: the stepper and `showFirstRunWalkthrough`
|
||||
(a Material bottom sheet on phones, a dialog on wide windows, via
|
||||
`showAppDetails`).
|
||||
- `walkthrough_harness_command.dart`: agent chips, the command and copy.
|
||||
- `walkthrough_gate.dart`: the first-launch and empty-server check.
|
||||
- `lib/application/pipelines_app.dart`: wraps the Pipelines destination body in
|
||||
the gate (the Pipelines tab is the first screen).
|
||||
- `lib/features/settings/settings_walkthrough_section.dart`: one row in the
|
||||
Tools → Help group, plus `SettingsKeys.walkthrough`.
|
||||
|
||||
## Focused tests
|
||||
|
||||
- `test/features/walkthrough/walkthrough_gate_test.dart`: first launch shows
|
||||
once; Done and Skip persist; a seen device on an empty server is offered once;
|
||||
a seen device that starts disconnected makes no server call and is offered
|
||||
after it connects; an unreadable check is retried on the next connection (and
|
||||
a repeated notification while connected does not re-query); a server with
|
||||
work, an unreadable server, a hidden Pipelines page, and an unavailable store
|
||||
all stay quiet; hiding the Pipelines page while the first-launch read is
|
||||
still pending keeps the walkthrough closed, and showing it again offers it
|
||||
once.
|
||||
- `test/features/walkthrough/first_run_walkthrough_test.dart`: phone bottom
|
||||
sheet and wide dialog; Back disabled on page 1; four pages with Done on the
|
||||
last and Skip throughout; the harness picker and copy; large text (2x) and
|
||||
dark mode without overflow.
|
||||
- `test/features/settings/settings_walkthrough_test.dart`: the Settings row
|
||||
reopens the walkthrough on page 1.
|
||||
|
||||
## Results
|
||||
|
||||
- Focused run: `tool/memwatch/full.sh 'test/features/walkthrough/first_run_walkthrough_test.dart test/features/walkthrough/walkthrough_gate_test.dart test/features/settings/settings_walkthrough_test.dart'`
|
||||
→ PASS, 20 passed, 0 failed, peak 1031 MB, 16 s. The verdict named only these
|
||||
three paths.
|
||||
- Visibility fix (review must-fix, visit 2): the gate offered without checking
|
||||
`enabled`, so a walkthrough could open over another destination if Pipelines
|
||||
was hidden before the post-frame callback or during a pending read. The gate
|
||||
now checks `mounted && enabled` in the callback, after each await, and before
|
||||
each show. A skipped callback clears the in-flight flag, so re-enabling
|
||||
Pipelines reschedules the offer. Covered by the new gate test
|
||||
"hiding Pipelines while an offer is pending keeps the walkthrough closed".
|
||||
That test was not run against the pre-fix code, so the failing-before claim
|
||||
is by reasoning only.
|
||||
- Lifecycle fix (review must-fix): the empty-server check used to run once
|
||||
right after the first frame, before the session connected. A seen device
|
||||
then got a `NotConnectedError`, and the check was never retried. The gate now
|
||||
takes the session as its connection source (`connection` + `connected`), waits
|
||||
while disconnected, re-runs on each new connection until the server answers,
|
||||
and stays quiet on a repeated notification while connected. A connection that
|
||||
arrives between frames requests a visual update, so the post-frame callback
|
||||
runs. The fix is covered by the two new gate tests above.
|
||||
- Two earlier runs failed and were fixed in the test code, not by weakening
|
||||
expectations: the large-text test tapped Next before scrolling it into view,
|
||||
and the "unavailable store" test awaited the real preferences plugin inside
|
||||
`testWidgets` and hung. The store now takes an injectable opener, so that case
|
||||
is a plain test with a null opener.
|
||||
- `tool/analyze.sh`: clean (0 errors, 0 warnings, 0 infos).
|
||||
- Not run here: `pipelines_app_test`, the Settings screen suites and the other
|
||||
Pipelines suites. They belong to the land gate.
|
||||
|
||||
## Affected states (checked by focused tests only; nothing captured)
|
||||
|
||||
- Phone (390×844): bottom sheet; page 1 with Back disabled; all four pages;
|
||||
Skip mid-walkthrough.
|
||||
- Wide (1280×900): dialog; Next reaches page 2.
|
||||
- Harness page: four agent chips; the command follows the selected agent; copy
|
||||
copies the selected command and the button shows a check.
|
||||
- Large text (2×) on a 360×740 phone and dark mode: every page builds with no
|
||||
exception.
|
||||
- Gate: first launch once; Done and Skip persist; a seen device on an empty
|
||||
server is offered once per server; a server with runs, an unreadable server,
|
||||
a hidden Pipelines page and an unavailable store stay quiet.
|
||||
- Settings: "Show the walkthrough" reopens page 1 and does not change the seen
|
||||
record.
|
||||
|
||||
Nothing was built, run on a device or captured. `ui-review` owns the rendered
|
||||
review.
|
||||
|
||||
## Limitations
|
||||
|
||||
- The gate is tested in isolation with fake stores and gateways. The Pipelines
|
||||
wiring in `pipelines_app.dart` is not covered by a focused test.
|
||||
- Narrow window: the empty-server offer marks the server as offered before it
|
||||
shows. If Pipelines is hidden during that one store write, the server is
|
||||
consumed without the walkthrough appearing. Fixing it needs the store write
|
||||
to move to the dialog's close, which changes when the offer is recorded.
|
||||
- On phones the walkthrough is a Material bottom sheet, not a full page.
|
||||
- The harness command is shown as a picker with one copy button for the
|
||||
selected agent, not four separate copy buttons.
|
||||
- The "Show the walkthrough" test covers the row, not the whole Settings tree.
|
||||
@@ -0,0 +1,36 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:flutter_test/flutter_test.dart';
|
||||
import 'package:pipelines_app/features/settings/settings_keys.dart';
|
||||
import 'package:pipelines_app/features/settings/settings_walkthrough_section.dart';
|
||||
import 'package:pipelines_app/ui/theme/app_theme.dart';
|
||||
|
||||
void main() {
|
||||
testWidgets('Settings reopens the walkthrough on the first page', (
|
||||
tester,
|
||||
) async {
|
||||
tester.view.devicePixelRatio = 1;
|
||||
tester.view.physicalSize = const Size(390, 844);
|
||||
addTearDown(tester.view.resetPhysicalSize);
|
||||
addTearDown(tester.view.resetDevicePixelRatio);
|
||||
|
||||
await tester.pumpWidget(
|
||||
MaterialApp(
|
||||
theme: appLightTheme(),
|
||||
home: const Scaffold(body: SettingsWalkthroughSection()),
|
||||
),
|
||||
);
|
||||
|
||||
expect(find.text('Show the walkthrough'), findsOneWidget);
|
||||
expect(find.text('Welcome to Pipelines'), findsNothing);
|
||||
|
||||
await tester.tap(find.byKey(SettingsKeys.walkthrough));
|
||||
await tester.pumpAndSettle();
|
||||
|
||||
expect(find.text('Welcome to Pipelines'), findsOneWidget);
|
||||
expect(find.text('Step 1 of 4'), findsOneWidget);
|
||||
|
||||
await tester.tap(find.byKey(const ValueKey<String>('walkthrough.skip')));
|
||||
await tester.pumpAndSettle();
|
||||
expect(find.text('Welcome to Pipelines'), findsNothing);
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,202 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:flutter/services.dart';
|
||||
import 'package:flutter_test/flutter_test.dart';
|
||||
import 'package:pipelines_app/features/walkthrough/first_run_walkthrough.dart';
|
||||
import 'package:pipelines_app/features/walkthrough/walkthrough_steps.dart';
|
||||
import 'package:pipelines_app/ui/theme/app_theme.dart';
|
||||
|
||||
const _nextKey = ValueKey<String>('walkthrough.next');
|
||||
const _backKey = ValueKey<String>('walkthrough.back');
|
||||
const _skipKey = ValueKey<String>('walkthrough.skip');
|
||||
const _copyKey = ValueKey<String>('walkthrough.copy');
|
||||
const _commandKey = ValueKey<String>('walkthrough.command');
|
||||
const _launchKey = ValueKey<String>('launch');
|
||||
|
||||
Widget _launcher({ThemeMode mode = ThemeMode.light, double textScale = 1}) =>
|
||||
MaterialApp(
|
||||
theme: appLightTheme(),
|
||||
darkTheme: appDarkTheme(),
|
||||
themeMode: mode,
|
||||
builder: (context, child) => MediaQuery(
|
||||
data: MediaQuery.of(
|
||||
context,
|
||||
).copyWith(textScaler: TextScaler.linear(textScale)),
|
||||
child: child!,
|
||||
),
|
||||
home: Scaffold(
|
||||
body: Builder(
|
||||
builder: (context) => Center(
|
||||
child: FilledButton(
|
||||
key: _launchKey,
|
||||
onPressed: () => showFirstRunWalkthrough(context),
|
||||
child: const Text('Open'),
|
||||
),
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
|
||||
Future<void> _open(WidgetTester tester) async {
|
||||
await tester.tap(find.byKey(_launchKey));
|
||||
await tester.pumpAndSettle();
|
||||
}
|
||||
|
||||
void _useViewport(WidgetTester tester, Size size) {
|
||||
tester.view.devicePixelRatio = 1;
|
||||
tester.view.physicalSize = size;
|
||||
addTearDown(tester.view.resetPhysicalSize);
|
||||
addTearDown(tester.view.resetDevicePixelRatio);
|
||||
}
|
||||
|
||||
void main() {
|
||||
group('phone layout', () {
|
||||
testWidgets('opens as a bottom sheet with the first page', (tester) async {
|
||||
_useViewport(tester, const Size(390, 844));
|
||||
await tester.pumpWidget(_launcher());
|
||||
await _open(tester);
|
||||
|
||||
expect(find.byType(BottomSheet), findsOneWidget);
|
||||
expect(find.byType(Dialog), findsNothing);
|
||||
expect(find.text('Step 1 of 4'), findsOneWidget);
|
||||
expect(find.text(walkthroughSteps.first.title), findsOneWidget);
|
||||
});
|
||||
|
||||
testWidgets('Back is disabled on the first page; Next advances', (
|
||||
tester,
|
||||
) async {
|
||||
_useViewport(tester, const Size(390, 844));
|
||||
await tester.pumpWidget(_launcher());
|
||||
await _open(tester);
|
||||
|
||||
expect(tester.widget<TextButton>(find.byKey(_backKey)).onPressed, isNull);
|
||||
await tester.tap(find.byKey(_nextKey));
|
||||
await tester.pumpAndSettle();
|
||||
expect(find.text('Step 2 of 4'), findsOneWidget);
|
||||
expect(
|
||||
tester.widget<TextButton>(find.byKey(_backKey)).onPressed,
|
||||
isNotNull,
|
||||
);
|
||||
|
||||
await tester.tap(find.byKey(_backKey));
|
||||
await tester.pumpAndSettle();
|
||||
expect(find.text('Step 1 of 4'), findsOneWidget);
|
||||
});
|
||||
|
||||
testWidgets('walks four pages, Done on the last, Skip on every page', (
|
||||
tester,
|
||||
) async {
|
||||
_useViewport(tester, const Size(390, 844));
|
||||
await tester.pumpWidget(_launcher());
|
||||
await _open(tester);
|
||||
|
||||
for (var page = 0; page < 3; page++) {
|
||||
expect(find.byKey(_skipKey), findsOneWidget);
|
||||
expect(find.text('Next'), findsOneWidget);
|
||||
await tester.tap(find.byKey(_nextKey));
|
||||
await tester.pumpAndSettle();
|
||||
}
|
||||
expect(find.text('Step 4 of 4'), findsOneWidget);
|
||||
expect(find.text('Done'), findsOneWidget);
|
||||
expect(find.byKey(_skipKey), findsOneWidget);
|
||||
expect(find.text(walkthroughSteps.last.title), findsOneWidget);
|
||||
|
||||
await tester.tap(find.text('Done'));
|
||||
await tester.pumpAndSettle();
|
||||
expect(find.text(walkthroughSteps.last.title), findsNothing);
|
||||
});
|
||||
|
||||
testWidgets('Skip closes from the middle of the walkthrough', (
|
||||
tester,
|
||||
) async {
|
||||
_useViewport(tester, const Size(390, 844));
|
||||
await tester.pumpWidget(_launcher());
|
||||
await _open(tester);
|
||||
await tester.tap(find.byKey(_nextKey));
|
||||
await tester.pumpAndSettle();
|
||||
|
||||
await tester.tap(find.byKey(_skipKey));
|
||||
await tester.pumpAndSettle();
|
||||
expect(find.byType(BottomSheet), findsNothing);
|
||||
});
|
||||
});
|
||||
|
||||
testWidgets('wide windows open the walkthrough as a dialog', (tester) async {
|
||||
_useViewport(tester, const Size(1280, 900));
|
||||
await tester.pumpWidget(_launcher());
|
||||
await _open(tester);
|
||||
|
||||
expect(find.byType(Dialog), findsOneWidget);
|
||||
expect(find.byType(BottomSheet), findsNothing);
|
||||
expect(find.text('Step 1 of 4'), findsOneWidget);
|
||||
await tester.tap(find.byKey(_nextKey));
|
||||
await tester.pumpAndSettle();
|
||||
expect(find.text(walkthroughSteps[1].title), findsOneWidget);
|
||||
});
|
||||
|
||||
testWidgets('the harness page offers each agent and copies its command', (
|
||||
tester,
|
||||
) async {
|
||||
_useViewport(tester, const Size(390, 844));
|
||||
final copied = <String>[];
|
||||
TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
|
||||
.setMockMethodCallHandler(SystemChannels.platform, (call) async {
|
||||
if (call.method == 'Clipboard.setData') {
|
||||
copied.add((call.arguments as Map)['text'] as String);
|
||||
}
|
||||
return null;
|
||||
});
|
||||
addTearDown(
|
||||
() => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
|
||||
.setMockMethodCallHandler(SystemChannels.platform, null),
|
||||
);
|
||||
|
||||
await tester.pumpWidget(_launcher());
|
||||
await _open(tester);
|
||||
await tester.tap(find.byKey(_nextKey));
|
||||
await tester.pumpAndSettle();
|
||||
|
||||
expect(
|
||||
tester.widget<SelectableText>(find.byKey(_commandKey)).data,
|
||||
'pipelines harness setup claude',
|
||||
);
|
||||
await tester.tap(
|
||||
find.byKey(const ValueKey<String>('walkthrough.agent.pi')),
|
||||
);
|
||||
await tester.pumpAndSettle();
|
||||
expect(
|
||||
tester.widget<SelectableText>(find.byKey(_commandKey)).data,
|
||||
'pipelines harness setup pi',
|
||||
);
|
||||
|
||||
await tester.tap(find.byKey(_copyKey));
|
||||
await tester.pumpAndSettle();
|
||||
expect(copied, ['pipelines harness setup pi']);
|
||||
expect(
|
||||
find.descendant(
|
||||
of: find.byKey(_copyKey),
|
||||
matching: find.byIcon(Icons.check),
|
||||
),
|
||||
findsOneWidget,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('large text and dark mode lay out without overflow', (
|
||||
tester,
|
||||
) async {
|
||||
_useViewport(tester, const Size(360, 740));
|
||||
await tester.pumpWidget(_launcher(mode: ThemeMode.dark, textScale: 2));
|
||||
await _open(tester);
|
||||
|
||||
for (var page = 0; page < walkthroughSteps.length; page++) {
|
||||
expect(tester.takeException(), isNull, reason: 'page $page');
|
||||
expect(find.text(walkthroughSteps[page].title), findsOneWidget);
|
||||
if (page < walkthroughSteps.length - 1) {
|
||||
// At 2x text the phone sheet scrolls, so Next can start off screen.
|
||||
await tester.ensureVisible(find.byKey(_nextKey));
|
||||
await tester.tap(find.byKey(_nextKey));
|
||||
await tester.pumpAndSettle();
|
||||
}
|
||||
}
|
||||
expect(tester.takeException(), isNull);
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,341 @@
|
||||
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);
|
||||
},
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user