diff --git a/docs.json b/docs.json index 6e95db4b4..f106f934b 100644 --- a/docs.json +++ b/docs.json @@ -30,11 +30,18 @@ } ], "sidebar": [ - ["About", "/"], - ["Getting started", "/getting-started"], - ["Patrol 3.0 is here!", "/v3"], - ["New package - patrol_finders", "/patrol-finders-release"], - ["Supported platforms", "/supported-platforms"], + + ["Patrol by LeanCode", "/"], + ["Improved logging and reporting is here!", "logs-announcement"], + [ + "Introduction", + [ + ["Getting started", "/getting-started"], + ["Logs and test results", "/logs"], + ["Supported platforms", "/supported-platforms"], + ["Compatibility table", "/compatibility-table"] + ] + ], [ "Finders", [ @@ -79,10 +86,21 @@ ["Browserstack", "/integrations/browserstack"] ] ], - ["Effective Patrol", "/effective-patrol"], - ["Tips and tricks", "/tips-and-tricks"], - ["Debugging Patrol tests", "/debugging-patrol-tests"], - ["Compatibility table", "/compatibility-table"], - ["LeanCode", "https://leancode.co"] + [ + "Announcements", + [ + ["Patrol 3.0 is here!", "/v3"], + ["New package - patrol_finders", "/patrol-finders-release"] + ] + ], + [ + "Other", + [ + ["Effective Patrol", "/effective-patrol"], + ["Tips and tricks", "/tips-and-tricks"], + ["Debugging Patrol tests", "/debugging-patrol-tests"], + ["LeanCode", "https://leancode.co"] + ] + ] ] } diff --git a/docs/logs-announcement.mdx b/docs/logs-announcement.mdx new file mode 100644 index 000000000..3ec5f9b58 --- /dev/null +++ b/docs/logs-announcement.mdx @@ -0,0 +1,16 @@ +--- +title: Improved logging and reporting is here! +--- + +# Big Update: Enhanced Logging and Test Reporting! + +We’ve made some major improvements to how you can monitor and analyze your tests! With Patrol 3.13.0 and later, you’ll get: + + - Verbose logging: Test names are now displayed in real time as they’re executed! + - Detailed step reporting: See every action Patrol takes during your test execution, giving you deeper insights into the process. + - Flutter logs in console: Now you can access Flutter logs directly within the patrol test output, streamlining debugging and analysis. +These enhancements will make it easier than ever to understand what's happening behind the code. + +For a full breakdown of these updates, check out the [Logs and test results][logs] page! + +[logs]: /logs \ No newline at end of file diff --git a/docs/logs.mdx b/docs/logs.mdx new file mode 100644 index 000000000..9f007203c --- /dev/null +++ b/docs/logs.mdx @@ -0,0 +1,125 @@ +--- +title: Logs and test results +--- + +# Logs and test results + +Once you've written and executed your tests, it's essential to monitor their results. Patrol provides two main methods for reporting test outcomes: **console logs** and **native test reports**. + +## Logging test steps + + +This feature is available starting from version `3.13.0`. + +If you're using this version but don't see logs for test steps, check if you're passing a custom `PatrolTesterConfig` to `patrolTest()`. If so, ensure the `printLogs: true` argument is included in the constructor. + + +During test execution, every test step (e.g., `tap` or `enterText`) is logged to the console along with its status. Additionally, the test name, status, and execution time are displayed. + +**Example console output:** + +``` +... +πŸ§ͺ denies various permissions + βœ… 1. scrollTo widgets with text "Open permissions screen". + βœ… 2. scrollTo widgets with text "Open permissions screen". + βœ… 3. tap widgets with text "Open permissions screen". + βœ… 4. tap widgets with text "Request camera permission". + βœ… 5. isPermissionDialogVisible (native) + βœ… 6. tap widgets with text "Request camera permission". + βœ… 7. isPermissionDialogVisible (native) + ⏳ 8. denyPermission (native) +❌ denies various permissions (integration_test/permissions/deny_many_permissions_twice_test.dart) (9s) +══║ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK β•žβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• +The following PlatformException was thrown running a test: +PlatformException(PermissionHandler.PermissionManager, A request +for permissions is already running, please wait for it to finish +before doing another request (note that you can request multiple +permissions at the same time)., null, null) + +When the exception was thrown, this was the stack: +#0 StandardMethodCodec.decodeEnvelope (package:flutter/src/services/message_codecs.dart:648:7) +#1 MethodChannel._invokeMethod (package:flutter/src/services/platform_channel.dart:334:18) + +#2 MethodChannelPermissionHandler.requestPermissions (package:permission_handler_platform_interface/src/method_channel/method_channel_permission_handler.dart:79:9) + +#3 PermissionActions.request (package:permission_handler/permission_handler.dart:52:31) + +#4 _PermissionsScreenState._requestCameraPermission (package:e2e_app/permissions_screen.dart:21:20) + + +The test description was: + denies various permissions +═════════════════════════════════════════════════════════════════ + +βœ… taps on notification (integration_test/permissions/notifications_test.dart) (16s) +βœ… taps on notification native2 (integration_test/permissions/notifications_test.dart) (14s) +βœ… grants various permissions (integration_test/permissions/permissions_many_test.dart) (15s) +... +``` + +## Test summary + +Once the tests are complete, a summary is printed: + + +``` +Test summary: +πŸ“ Total: 8 +βœ… Successful: 3 +❌ Failed: 5 + - taps on notification (integration_test/permissions/notifications_test.dart) + - taps on notification native2 (integration_test/permissions/notifications_test.dart) + - accepts location permission (integration_test/permissions/permissions_location_test.dart) + - accepts location permission native2 (integration_test/permissions/permissions_location_test.dart) + - grants various permissions (integration_test/permissions/permissions_many_test.dart) +⏩ Skipped: 0 +πŸ“Š Report: file:///Users/user/patrol/dev/e2e_app/build/app/reports/androidTests/connected/index.html +⏱️ Duration: 227s +``` + +## Customizing log behavior + +You can customize which logs are displayed by using the following flags. These can be passed to the `patrol test` or `patrol develop` commands: + +| Flag | Description | Available in | Default value | +| ------------------------- | ------------------------------------------ | -------------------------------------------------- | ------------- | +| --[no-]show-flutter-logs | Show Flutter logs while running the tests. | `patrol test`, in `patrol develop` it's always on | `false` | +| --[no-]hide-test-steps | Hide test steps while running the tests. | `patrol test` and `patrol develop` | `false` | +| --[no-]clear-test-steps | Clear test steps after the test finishes. | `patrol test` | `true` | + +## Native test reports + +In addition to console logs, you can review test results in a **native test report**. The report's file path is provided in the test summary, for example: + +``` +πŸ“Š Report: file:///Users/user/patrol/dev/e2e_app/build/app/reports/androidTests/connected/index.html +``` + +## Logs in `patrol_finders` + +By default, enhanced logs are disabled when using `patrol_finders` without the `patrol` package. To enable them, pass the `printLogs: true` argument to the `PatrolTesterConfig` constructor: + +``` +patrolWidgetTest( + 'throws exception when no widget to tap on is found', + config: const PatrolTesterConfig(printLogs: true), + (tester) async { + // test body + // ... + }, +); +``` +``` +testWidgets( + 'description', + (widgetTester) async { + final $ = PatrolTester( + tester: widgetTester, + config: PatrolTesterConfig(printLogs: true), + ); + // test body + // ... + }, +); +```