From dbd525a7b11b0bbb30b162f6f95921680a9e4383 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 12 Nov 2026 01:02:31 +0000 Subject: [PATCH] Clarify empty server states Show calm, actionable empty states for pipelines, runs, and chats while keeping filtered and failed loads distinct. Add focused widget coverage and document the remaining verification limits. --- .../chat/ui/sessions/chat_sessions_body.dart | 2 +- .../features/pipelines/pipeline_filter.dart | 11 +++- .../widgets/pipeline_list_panel.dart | 9 +++ app/lib/features/runs/ui/runs_list.dart | 26 ++++++-- app/notes/empty-server-states.md | 61 +++++++++++++++++++ .../ui/sessions/chat_ios_material_test.dart | 4 +- .../sessions/chat_sessions_screen_test.dart | 7 ++- .../pipelines/pipeline_filter_test.dart | 2 +- .../pipelines_empty_server_test.dart | 50 +++++++++++++++ .../pipelines_screen_filter_test.dart | 3 +- .../runs/ui/runs_list_widget_test.dart | 43 ++++++++++++- 11 files changed, 201 insertions(+), 17 deletions(-) create mode 100644 app/notes/empty-server-states.md create mode 100644 app/test/features/pipelines/pipelines_empty_server_test.dart diff --git a/app/lib/features/chat/ui/sessions/chat_sessions_body.dart b/app/lib/features/chat/ui/sessions/chat_sessions_body.dart index c0195db6..7cddbbb2 100644 --- a/app/lib/features/chat/ui/sessions/chat_sessions_body.dart +++ b/app/lib/features/chat/ui/sessions/chat_sessions_body.dart @@ -84,7 +84,7 @@ class ChatSessionsBody extends StatelessWidget { emptyMessageOverride ?? (sessions.isEmpty ? error == null - ? 'No chat sessions on this server yet.' + ? 'No chats yet. Use New chat to start one.' : null : 'No chats match "${query.trim()}".'); diff --git a/app/lib/features/pipelines/pipeline_filter.dart b/app/lib/features/pipelines/pipeline_filter.dart index 9ed8a8ca..77f5c3da 100644 --- a/app/lib/features/pipelines/pipeline_filter.dart +++ b/app/lib/features/pipelines/pipeline_filter.dart @@ -77,11 +77,13 @@ class PipelineFilters { ); } -/// The empty-state sentence for the list plus its optional reset action. +/// The empty-state sentence for the list, an optional line naming the next +/// step, and an optional reset action. class PipelineEmptyState { - const PipelineEmptyState(this.message, {this.clearAction}); + const PipelineEmptyState(this.message, {this.detail, this.clearAction}); final String message; + final String? detail; final String? clearAction; } @@ -153,7 +155,10 @@ PipelineEmptyState? pipelineListEmptyState( ) { if (items.isNotEmpty) return null; if (all.isEmpty) { - return const PipelineEmptyState('No pipelines are defined on this server.'); + return const PipelineEmptyState( + 'No pipelines yet.', + detail: 'Create one from a template in Templates.', + ); } final name = filters.name; final onlyName = diff --git a/app/lib/features/pipelines/widgets/pipeline_list_panel.dart b/app/lib/features/pipelines/widgets/pipeline_list_panel.dart index f03b518d..20cb037d 100644 --- a/app/lib/features/pipelines/widgets/pipeline_list_panel.dart +++ b/app/lib/features/pipelines/widgets/pipeline_list_panel.dart @@ -192,6 +192,15 @@ class PipelineListPanel extends StatelessWidget { textAlign: TextAlign.center, style: _mutedStyle(context), ), + if (empty.detail != null) + Padding( + padding: const EdgeInsets.only(top: 4), + child: Text( + empty.detail!, + textAlign: TextAlign.center, + style: _mutedStyle(context), + ), + ), if (empty.clearAction != null) PipelineTextButton( label: empty.clearAction!, diff --git a/app/lib/features/runs/ui/runs_list.dart b/app/lib/features/runs/ui/runs_list.dart index 3f5d149f..00817b55 100644 --- a/app/lib/features/runs/ui/runs_list.dart +++ b/app/lib/features/runs/ui/runs_list.dart @@ -163,18 +163,32 @@ class RunsList extends StatelessWidget { // Filtered and sorted once per build: the getter recomputes every read. final visible = controller.visibleRuns; if (visible.isNotEmpty) return _groupedRuns(context, header, visible); + // A server with no runs at all is not a filter problem: say what the list + // is for and where its first run comes from. A free-text query counts as + // a filter too, so a search on an empty server reads as "nothing found". + final noRunsAtAll = controller.runs.isEmpty && + controller.activeFilterCount == 0 && + controller.query.trim().isEmpty; return BelowTopBar( child: Column( crossAxisAlignment: CrossAxisAlignment.stretch, children: [ ...header, Expanded( - child: _state( - context, - icon: const Icon(Icons.inbox_outlined), - title: 'No runs found.', - subtitle: 'Try changing or clearing the filters.', - ), + child: noRunsAtAll + ? _state( + context, + icon: const Icon(Icons.inbox_outlined), + title: 'No runs yet.', + subtitle: + 'Start one from Pipelines and its runs appear here.', + ) + : _state( + context, + icon: const Icon(Icons.inbox_outlined), + title: 'No runs found.', + subtitle: 'Try changing or clearing the filters.', + ), ), ], ), diff --git a/app/notes/empty-server-states.md b/app/notes/empty-server-states.md new file mode 100644 index 00000000..5869c91e --- /dev/null +++ b/app/notes/empty-server-states.md @@ -0,0 +1,61 @@ +# Empty-server states (Pipelines, Runs, Chat) + +On a brand-new server (no pipelines, runs or chats) the healthy empty reply +should read as "nothing here yet" with the next step, not as a filter problem +or a missing list. Real failures keep their error treatment and never show the +empty copy. + +## Changed states + +| Destination | Before (empty, healthy server) | After | +| --- | --- | --- | +| Pipelines list | "No pipelines are defined on this server." | "No pipelines yet." + "Create one from a template in Templates." | +| Runs list | "No runs found." + "Try changing or clearing the filters." | "No runs yet." + "Start one from Pipelines and its runs appear here." | +| Runs list, filter hides every run | (same as above) | unchanged: "No runs found." + filter hint | +| Chat list | "No chat sessions on this server yet." | "No chats yet. Use New chat to start one." | + +Source: `lib/features/pipelines/pipeline_filter.dart`, +`lib/features/pipelines/widgets/pipeline_list_panel.dart` (renders the new +`PipelineEmptyState.detail` line), `lib/features/runs/ui/runs_list.dart`, +`lib/features/chat/ui/sessions/chat_sessions_body.dart`. + +Unchanged error paths: a failed Pipelines list shows its error banner with +Retry; a failed Runs list shows the error with Retry; a failed chat load hides +the empty message and shows the reason. + +## Focused results + +Command (from `app/`): `tool/memwatch/full.sh 'test/features/pipelines/pipelines_empty_server_test.dart test/features/pipelines/pipeline_filter_test.dart test/features/pipelines/pipelines_screen_filter_test.dart test/features/runs/ui/runs_list_widget_test.dart test/features/chat/ui/sessions/chat_sessions_screen_test.dart test/features/chat/ui/sessions/chat_ios_material_test.dart'` + +- Before the source change (new and updated expectations): 18 passed, 6 failed, + as expected on the old copy. The new test file also failed to compile + (missing `Key` import), fixed before the rerun. +- After the change: PASS, 25 passed, 0 failed, peak 1484 MB, 5s. +- Review fix (runs must-fix): the no-runs state now also requires an empty + free-text query, so an empty server with a search query shows "No runs + found." with the filter hint. Covered by a new widget test in + `runs_list_widget_test.dart`. Focused rerun of that file: PASS, 6 passed, + 0 failed, peak 768 MB, 4s. +- `tool/analyze.sh`: clean (rerun after the review fix). + +New or extended coverage: + +- `test/features/pipelines/pipelines_empty_server_test.dart`: empty server shows + the no-pipelines state and next step, with no spinner, list or Retry; a failed + list still shows the error and not the empty copy. +- `test/features/runs/ui/runs_list_widget_test.dart`: loading, error, and + server-empty states stay distinct; a status filter that hides every run keeps + the "No runs found." filter state. +- Chat and pipeline-filter expectations updated to the new copy. + +## Not verified here + +- No UI build or capture; `ui-review` owns rendered evidence. +- Schedules, Search, Settings, Usage/stats, Needs-you and Templates were read, + not changed or tested. Their empty copy is already calm, except that + "No schedules yet." has no next step because the list has no add action. + Stats says "No runs loaded." (secondary text, not an error). +- Runs and other error text still shows the raw error string (`'$e'`); this is + not an empty-server path and was not changed. +- Server gap: this stage did not check Go's empty-database replies. The client + treats an empty list as healthy. No Go change was made. diff --git a/app/test/features/chat/ui/sessions/chat_ios_material_test.dart b/app/test/features/chat/ui/sessions/chat_ios_material_test.dart index 35a82fd5..6643b588 100644 --- a/app/test/features/chat/ui/sessions/chat_ios_material_test.dart +++ b/app/test/features/chat/ui/sessions/chat_ios_material_test.dart @@ -17,7 +17,7 @@ void main() { expect(find.byType(Scaffold), findsWidgets); - const message = 'No chat sessions on this server yet.'; + const message = 'No chats yet. Use New chat to start one.'; expect(find.text(message), findsOneWidget); expectNormalTextStyle(tester, message); }); @@ -39,7 +39,7 @@ void main() { 'for this operator'; expect(find.text(message), findsOneWidget); expectNormalTextStyle(tester, message); - expect(find.text('No chat sessions on this server yet.'), findsNothing); + expect(find.text('No chats yet. Use New chat to start one.'), findsNothing); expect( find.ancestor( of: find.text('Retry'), diff --git a/app/test/features/chat/ui/sessions/chat_sessions_screen_test.dart b/app/test/features/chat/ui/sessions/chat_sessions_screen_test.dart index 1d01144a..c40846a4 100644 --- a/app/test/features/chat/ui/sessions/chat_sessions_screen_test.dart +++ b/app/test/features/chat/ui/sessions/chat_sessions_screen_test.dart @@ -91,7 +91,10 @@ void main() { ) async { final gateway = FakeChatGateway(); await pumpMaterialChat(tester, gateway); - expect(find.text('No chat sessions on this server yet.'), findsOneWidget); + expect( + find.text('No chats yet. Use New chat to start one.'), + findsOneWidget, + ); expect(find.textContaining('No chats match'), findsNothing); }); @@ -111,7 +114,7 @@ void main() { 'Bad state: server unavailable while listing chat sessions ' 'for this operator'; expect(find.text(message), findsOneWidget); - expect(find.text('No chat sessions on this server yet.'), findsNothing); + expect(find.text('No chats yet. Use New chat to start one.'), findsNothing); final messageBox = tester.renderObject(find.text(message)); expect( messageBox.size.height, diff --git a/app/test/features/pipelines/pipeline_filter_test.dart b/app/test/features/pipelines/pipeline_filter_test.dart index db91004c..18e5e34f 100644 --- a/app/test/features/pipelines/pipeline_filter_test.dart +++ b/app/test/features/pipelines/pipeline_filter_test.dart @@ -132,7 +132,7 @@ void main() { const [], const PipelineFilters(), )?.message, - 'No pipelines are defined on this server.', + 'No pipelines yet.', ); expect(pipelineListEmptyState(all, all, const PipelineFilters()), isNull); }); diff --git a/app/test/features/pipelines/pipelines_empty_server_test.dart b/app/test/features/pipelines/pipelines_empty_server_test.dart new file mode 100644 index 00000000..8c85ff51 --- /dev/null +++ b/app/test/features/pipelines/pipelines_empty_server_test.dart @@ -0,0 +1,50 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; + +import 'fixtures.dart'; +import 'test_helpers.dart'; + +/// A brand-new server: every list is empty and healthy. +FakeGateway emptyServerGateway() => FakeGateway( + (type, fields) => switch (type) { + 'list_pipelines' => pipelineListReply(const []), + 'list_runs' => runListReply(const []), + 'list_schedules' => {'type': 'schedules', 'schedules': []}, + _ => errorReply('unexpected $type'), + }, +); + +void main() { + testWidgets( + 'an empty server shows a calm no-pipelines state with the next step', + (tester) async { + await pumpWide(tester, emptyServerGateway()); + + expect(find.text('No pipelines yet.'), findsOneWidget); + expect( + find.text('Create one from a template in Templates.'), + findsOneWidget, + ); + expect(find.text('Loading pipelines…'), findsNothing); + expect(find.byKey(const Key('pipeline-list')), findsNothing); + expect(find.textContaining('not defined'), findsNothing); + expect(find.text('Retry'), findsNothing); + expect(tester.takeException(), isNull); + }, + ); + + testWidgets( + 'a failed list stays an error and never reads as an empty server', + (tester) async { + await pumpWide( + tester, + gatewayFor(PipelineFixture(), listFails: true, summaries: const []), + ); + + expect(find.textContaining('server offline'), findsOneWidget); + expect(find.text('No pipelines yet.'), findsNothing); + expect(find.text('Loading pipelines…'), findsNothing); + expect(tester.takeException(), isNull); + }, + ); +} diff --git a/app/test/features/pipelines/pipelines_screen_filter_test.dart b/app/test/features/pipelines/pipelines_screen_filter_test.dart index 65a5d88d..cab57568 100644 --- a/app/test/features/pipelines/pipelines_screen_filter_test.dart +++ b/app/test/features/pipelines/pipelines_screen_filter_test.dart @@ -98,8 +98,9 @@ void main() { MaterialApp(home: PipelinesScreen(gateway: emptyGateway)), ); await tester.pumpAndSettle(); + expect(find.text('No pipelines yet.'), findsOneWidget); expect( - find.text('No pipelines are defined on this server.'), + find.text('Create one from a template in Templates.'), findsOneWidget, ); }); diff --git a/app/test/features/runs/ui/runs_list_widget_test.dart b/app/test/features/runs/ui/runs_list_widget_test.dart index b316d8e6..607228b7 100644 --- a/app/test/features/runs/ui/runs_list_widget_test.dart +++ b/app/test/features/runs/ui/runs_list_widget_test.dart @@ -162,9 +162,50 @@ void main() { gateway.reply = {'runs': []}; await controller.load(); await tester.pumpAndSettle(); - expect(find.text('No runs found.'), findsOneWidget); + expect(find.text('No runs yet.'), findsOneWidget); + expect(find.textContaining('Start one from Pipelines'), findsOneWidget); + expect(find.text('No runs found.'), findsNothing); expect(find.textContaining('offline'), findsNothing); expect(tester.takeException(), isNull); + + // A filter that hides every run is a different state: say so and offer + // the filter as the way back, not a server with no runs. + controller.setStatus('failed'); + await tester.pumpAndSettle(); + expect(find.text('No runs found.'), findsOneWidget); + expect(find.text('No runs yet.'), findsNothing); + expect( + find.text('Try changing or clearing the filters.'), + findsOneWidget, + ); + expect(tester.takeException(), isNull); + }, + variant: TargetPlatformVariant.only(TargetPlatform.android), + ); + + testWidgets( + 'an empty server with a search query reads as no match, not no runs', + (tester) async { + gateway.failure = null; + gateway.gate = null; + gateway.reply = {'runs': []}; + await controller.load(); + controller.setQuery('deploy'); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: RunsList(controller: controller, onSelected: (_) {}), + ), + ), + ); + await tester.pumpAndSettle(); + expect(find.text('No runs found.'), findsOneWidget); + expect(find.text('No runs yet.'), findsNothing); + expect( + find.text('Try changing or clearing the filters.'), + findsOneWidget, + ); + expect(tester.takeException(), isNull); }, variant: TargetPlatformVariant.only(TargetPlatform.android), );