Refactor/organize source test modules And Implement capture screenshots with Flutter CLI

.github/workflows/docs-check.yml

@@ -7,10 +7,10 @@ on:
     paths:
       - "docs/**"
       - "lib/src/cli.dart"
-      - "lib/src/scenario_dsl_docs.dart"
+      - "lib/src/scenario/scenario_dsl_docs.dart"
       - "tool/check_*_docs.dart"
       - "tool/generate_*_docs.dart"
-      - "test/*docs*_test.dart"
+      - "test/**docs*_test.dart"
       - "package.json"
       - "package-lock.json"
       - ".github/workflows/docs-check.yml"
@@ -49,7 +49,7 @@ jobs:
         run: dart analyze --fatal-infos --fatal-warnings
 
       - name: Test docs examples
-        run: dart test test/scenario_dsl_docs_test.dart test/scenario_dsl_docs_tool_test.dart
+        run: dart test test/scenario/scenario_dsl_docs_test.dart test/scenario/scenario_dsl_docs_tool_test.dart
 
       - name: Check Scenario DSL docs
         run: dart run tool/check_scenario_dsl_docs.dart

CONTEXT.md

@@ -24,6 +24,10 @@ _Avoid_: Scenario Suite, full test, all YAML files
 A Flutter Pilot execution that runs multiple Project Scenarios as one batch for a Target App Package. A Project Run has one batch-level run directory that groups each Scenario Run directory and a project-level summary report.
 _Avoid_: Full test run, test suite run, all-Scenario run
 
+**Test Execution Session**:
+The shared execution lifetime inside `flutter_pilot test` that prepares one launched Target App Package for Scenario execution, exposes the Runtime Target and Target Device selected for that launch, handles launch progress and interruption, and owns cleanup. A single Entry Scenario uses one Test Execution Session for one Scenario Run; a Project Run uses one Test Execution Session across multiple Project Scenarios with hot restarts between later Scenarios.
+_Avoid_: Run command, Project Run, Scenario Run
+
 **Runtime Target**:
 The running Flutter app instance that a Scenario is executed against. Connection details for the Runtime Target are provided outside the Scenario.
 _Avoid_: Target configuration, environment block

issues/0.1.1-pilot-runtime.md

@@ -301,23 +301,39 @@ Verification:
 
 - 6. Implement byKey and byWidget Finder resolution
 
-## 10. Implement Flutter-layer screenshot capture
+## 10. Implement Flutter CLI device screenshot capture
+
+Status: completed in `c1f4572 feat(runtime): capture screenshots with Flutter CLI`.
 
 ## Parent
 
 https://github.com/drown0315/flutter_pilot/issues/110
 
 ## What to build
 
-Implement screenshot capture for `pilot_runtime` using a Flutter-layer or Flutter Inspector screenshot path. The result should map through `PilotRuntimeAdapter` into Flutter Pilot's existing screenshot artifact flow without using device screenshots.
+Implement screenshot capture for the `pilot_runtime` adapter path using
+`flutter screenshot -d <device>`. The result should map through
+`PilotRuntimeAdapter` into Flutter Pilot's existing screenshot artifact flow
+as PNG bytes.
+
+Decision note: this issue originally preferred a Flutter-layer or Inspector
+screenshot path and explicitly avoided device screenshots. The implementation
+uses the Flutter CLI device screenshot path by product decision for this slice.
 
 ## Acceptance criteria
 
-- [ ] `pilot_runtime` exposes screenshot capture returning image bytes and MIME type.
-- [ ] `PilotRuntimeAdapter.captureScreenshot()` maps the runtime result to Flutter Pilot `ScreenshotCapture`.
-- [ ] The implementation uses a Flutter-layer or Inspector screenshot path, not a device screenshot.
-- [ ] Screenshot capture failures map to Runtime Adapter operation failures.
-- [ ] Tests cover success bytes/MIME mapping and failure mapping.
+- [x] `PilotRuntimeAdapter.captureScreenshot()` returns Flutter Pilot `ScreenshotCapture` with PNG bytes and MIME type.
+- [x] The implementation shells out to `flutter screenshot -d <device> --out <temp.png>`.
+- [x] The Target Device id is passed from explicit Target Device selection or Flutter machine launch output into the Runtime Target.
+- [x] Screenshot capture failures map to Runtime Adapter operation failures.
+- [x] Missing Target Device id fails clearly and asks the user to pass `--device`.
+- [x] Tests cover command construction, success bytes/MIME mapping, failure mapping, missing device handling, and launch device id propagation.
+
+Verification:
+
+- `dart format .`
+- `dart analyze`
+- `dart test`
 
 ## Blocked by
 

lib/flutter_pilot.dart

@@ -8,25 +8,25 @@ library;
 export 'src/cli.dart';
 export 'src/artifacts/artifact_store.dart';
 export 'src/app_setup.dart';
-export 'src/diagnostic_reducer.dart';
-export 'src/diagnostic_text_renderer.dart';
-export 'src/html_timeline_report.dart';
+export 'src/diagnostics/diagnostic_reducer.dart';
+export 'src/diagnostics/diagnostic_text_renderer.dart';
+export 'src/reports/html_timeline_report.dart';
 export 'src/recording/recording_contract.dart';
 export 'src/recording/screen_recorder_recording_controller.dart';
-export 'src/project_scenario_discovery.dart';
-export 'src/project_run_report.dart';
+export 'src/scenario/project_scenario_discovery.dart';
+export 'src/reports/project_run_report.dart';
 export 'src/runtime/pilot_runtime_adapter.dart';
 export 'src/runtime/pilot_runtime_vm_service.dart';
 export 'src/runtime/runtime_adapter_selector.dart';
 export 'src/runtime/runtime_contract.dart';
-export 'src/run_diff.dart';
-export 'src/scenario.dart';
-export 'src/scenario_dsl_docs.dart';
-export 'src/scenario_parser.dart';
-export 'src/scenario_runner.dart';
-export 'src/step_progress_renderer.dart';
-export 'src/target_app_launch_progress_renderer.dart';
-export 'src/target_app_launcher.dart';
-export 'src/target_device.dart';
-export 'src/test_command_support.dart';
+export 'src/diff/run_diff.dart';
+export 'src/scenario/scenario.dart';
+export 'src/scenario/scenario_dsl_docs.dart';
+export 'src/scenario/scenario_parser.dart';
+export 'src/execution/scenario_runner.dart';
+export 'src/target/step_progress_renderer.dart';
+export 'src/target/target_app_launch_progress_renderer.dart';
+export 'src/target/target_app_launcher.dart';
+export 'src/target/target_device.dart';
+export 'src/execution/test_command_support.dart';
 export 'src/terminal_style.dart';

lib/src/artifacts/artifact_store.dart

@@ -4,7 +4,7 @@ import 'dart:typed_data';
 
 import 'package:path/path.dart' as p;
 
-import '../scenario.dart';
+import '../scenario/scenario.dart';
 
 const JsonEncoder _artifactJsonEncoder = JsonEncoder.withIndent('  ');
 

lib/src/cli.dart

@@ -7,7 +7,7 @@ import 'commands/diff_command.dart';
 import 'commands/report_command.dart';
 import 'commands/test_command.dart';
 import 'commands/validate_command.dart';
-import 'test_command_support.dart';
+import 'execution/test_command_support.dart';
 
 /// Command-line entry point for Flutter Pilot.
 ///
@@ -25,13 +25,12 @@ class FlutterPilotCli {
   const FlutterPilotCli({
     TestCommandExecutor testCommandExecutor =
         const DefaultTestCommandExecutor(),
-    ProjectRunCommandExecutor projectRunCommandExecutor =
-        const DefaultProjectRunCommandExecutor(),
+    ProjectRunExecutor projectRunExecutor = const DefaultProjectRunExecutor(),
   }) : _testCommandExecutor = testCommandExecutor,
-       _projectRunCommandExecutor = projectRunCommandExecutor;
+       _projectRunExecutor = projectRunExecutor;
 
   final TestCommandExecutor _testCommandExecutor;
-  final ProjectRunCommandExecutor _projectRunCommandExecutor;
+  final ProjectRunExecutor _projectRunExecutor;
 
   /// Run the CLI with already-tokenized command-line arguments.
   ///
@@ -51,7 +50,7 @@ class FlutterPilotCli {
           ..addCommand(
             TestCommand(
               executor: _testCommandExecutor,
-              projectRunExecutor: _projectRunCommandExecutor,
+              projectRunExecutor: _projectRunExecutor,
             ),
           )
           ..addCommand(ReportCommand())

lib/src/commands/diff_command.dart

@@ -2,7 +2,7 @@ import 'dart:io';
 
 import 'package:args/command_runner.dart';
 
-import '../run_diff.dart';
+import '../diff/run_diff.dart';
 
 /// `diff` command for comparing two existing Scenario Run directories.
 ///

lib/src/commands/report_command.dart

@@ -2,7 +2,7 @@ import 'dart:io';
 
 import 'package:args/command_runner.dart';
 
-import '../html_timeline_report.dart';
+import '../reports/html_timeline_report.dart';
 
 /// `report` command for regenerating HTML from an existing run directory.
 ///

lib/src/commands/test_command.dart

@@ -3,22 +3,22 @@ import 'dart:io';
 
 import 'package:args/command_runner.dart';
 
-import '../diagnostic_text_renderer.dart';
-import '../project_scenario_discovery.dart';
-import '../scenario.dart';
-import '../scenario_parser.dart';
-import '../scenario_runner.dart';
-import '../step_progress_renderer.dart';
-import '../target_app_launch_progress_renderer.dart';
-import '../test_command_support.dart';
+import '../diagnostics/diagnostic_text_renderer.dart';
+import '../scenario/project_scenario_discovery.dart';
+import '../scenario/scenario.dart';
+import '../execution/scenario_runner.dart';
+import '../scenario/scenario_parser.dart';
+import '../target/step_progress_renderer.dart';
+import '../target/target_app_launch_progress_renderer.dart';
+import '../execution/test_command_support.dart';
 
 /// `test` command shell for validating CLI arguments before app launch.
 ///
 /// It checks Scenario YAML and validates `--until` / `--print` relationships
 class TestCommand extends Command<int> {
   TestCommand({
     required TestCommandExecutor executor,
-    required ProjectRunCommandExecutor projectRunExecutor,
+    required ProjectRunExecutor projectRunExecutor,
   }) : _executor = executor,
        _projectRunExecutor = projectRunExecutor {
     argParser
@@ -50,7 +50,7 @@ class TestCommand extends Command<int> {
   }
 
   final TestCommandExecutor _executor;
-  final ProjectRunCommandExecutor _projectRunExecutor;
+  final ProjectRunExecutor _projectRunExecutor;
 
   @override
   String get description => 'Launch the Target App Package and run a Scenario.';
@@ -216,7 +216,7 @@ class TestCommand extends Command<int> {
       _writeValidationErrors(error.errors);
       return 1;
     }
-    final ProjectRunCommandOptions options = ProjectRunCommandOptions(
+    final ProjectRunOptions options = ProjectRunOptions(
       discoveryRootPath: discoveryRootPath,
       scenarios: scenarios,
       device: device,
@@ -237,7 +237,7 @@ class TestCommand extends Command<int> {
             jsonOutput: options.jsonOutput,
             stderrHasTerminal: stderr.hasTerminal,
           );
-      final ProjectRunCommandReport report = await _projectRunExecutor.run(
+      final ProjectRunResult report = await _projectRunExecutor.run(
         options,
         onLaunchProgress: launchProgressRenderer?.render,
         launchHeartbeatEnabled: launchProgressRenderer != null,

lib/src/commands/validate_command.dart

@@ -3,7 +3,7 @@ import 'dart:io';
 
 import 'package:args/command_runner.dart';
 
-import '../scenario_parser.dart';
+import '../scenario/scenario_parser.dart';
 
 /// `validate` command for checking Scenario YAML without connecting to Flutter.
 ///

lib/src/diagnostic_text_renderer.dart → lib/src/diagnostics/diagnostic_text_renderer.dart

@@ -1,5 +1,5 @@
 import 'diagnostic_reducer.dart';
-import 'scenario_runner.dart';
+import '../execution/scenario_runner.dart';
 
 /// Renders printed diagnostics as terminal-friendly text.
 ///

lib/src/run_diff.dart → lib/src/diff/run_diff.dart

@@ -4,7 +4,7 @@ import 'dart:io';
 import 'package:crypto/crypto.dart';
 import 'package:path/path.dart' as p;
 
-import 'diagnostic_reducer.dart';
+import '../diagnostics/diagnostic_reducer.dart';
 
 /// Failure while loading or comparing Scenario Run reports.
 ///