Skip to main content
Patrol includes a comprehensive logging system through the patrol_log package. This system provides structured, real-time feedback about test execution, making it easier to debug failures and understand test behavior.

​
Overview

The patrol_log package is used internally by Patrol CLI to capture and display test execution information. While you typically don’t need to interact with it directly, understanding how it works can help you debug tests more effectively.
Logging is automatically configured when you use patrol test or patrol develop. The logs appear in your terminal as tests run.

​
Log Structure

Patrol logs are structured as JSON entries that get parsed and formatted for display. Each log entry has a specific type:

​
Entry Types

Test Entries

Mark the start, completion, failure, or skipping of individual tests.

Step Entries

Track individual test steps and actions within a test.

Log Entries

Custom log messages from your test code.

Error Entries

Capture errors and exceptions that occur during testing.

Warning Entries

Display warnings about configuration or test execution.

Config Entries

Store configuration information passed to the logging system.

​
Log Output Format

When you run Patrol tests, logs are displayed with emoji indicators for easy scanning: 
🧪 patrol_test/example_test.dart counter test
        ⏳   1. tap on increment button
        ✅   1. tap on increment button
        ⏳   2. verify counter incremented
        ✅   2. verify counter incremented
✅ patrol_test/example_test.dart counter test (3s)

​
Log Components

1

Test lifecycle

  • 🧪 Test started
  • ✅ Test passed
  • ❌ Test failed
  • ⏩ Test skipped
2

Step execution

  • ⏳ Step in progress
  • ✅ Step completed successfully
  • ❌ Step failed
3

Custom logs

  • 📝 Custom log message from test code
4

Summary

  • 📊 Report file path
  • ⏱️ Execution duration
  • Test counts (total, successful, failed, skipped)

​
Configuration Options

Patrol CLI provides several flags to control logging behavior:

​
Show Flutter Logs

Capture and display Flutter framework logs: 
patrol test --verbose
This shows all Flutter logs, including print() statements from your test code and framework debug output.

​
Hide Test Steps

Reduce output by hiding individual test steps: 
patrol test --no-test-steps
Hiding test steps can make it harder to debug failures, as you won’t see which specific step failed.

​
Clear Test Steps

Automatically clear successful test steps from the console: 
patrol test --clear-test-steps
This keeps the console clean by removing step logs after a test passes, but preserves them when tests fail.

​
Hide Test Lifecycle

Hide test start/end messages: 
patrol test --hide-test-lifecycle

​
Test Summary

After all tests complete, Patrol displays a summary: 
Test summary:
📝 Total: 10
✅ Successful: 8
❌ Failed: 2
  - patrol_test/login_test.dart invalid credentials test
  - patrol_test/checkout_test.dart payment failure test
⏩ Skipped: 0
📊 Report: /path/to/report.json
⏱️  Duration: 2m 34s
Failed tests are listed with their full file paths, making it easy to locate and fix them.

​
Advanced: Custom Logging

While not commonly needed, you can use the patrol_log package directly in custom tooling:

​
PatrolLogWriter

Creates and writes log entries: 
import 'package:patrol_log/patrol_log.dart';

final writer = PatrolLogWriter(config: {'printLogs': true});

// Log a custom message
writer.log(LogEntry(message: 'Custom log message'));

// Log a test event
writer.log(TestEntry(
  name: 'my_test',
  status: TestEntryStatus.start,
));

writer.close();

​
PatrolLogReader

Reads and parses log entries from test execution: 
import 'package:patrol_log/patrol_log.dart';
import 'package:dispose_scope/dispose_scope.dart';

final scope = DisposeScope();

final reader = PatrolLogReader(
  scope: scope,
  listenStdOut: (onData, {onError, onDone, cancelOnError}) {
    // Set up stdout listener
    return stdout.listen(onData, onError: onError, onDone: onDone);
  },
  log: print,
  reportPath: '/path/to/report.json',
  showFlutterLogs: true,
  hideTestSteps: false,
  clearTestSteps: false,
);

reader.listen();
reader.startTimer();

// After tests complete:
reader.stopTimer();
print(reader.summary);
The patrol_log package is primarily for internal use by Patrol CLI. Most users don’t need to interact with it directly.

​
Log Entry Details

Each log entry type has specific fields:

​
Test Entry

TestEntry(
  name: 'test_file.dart test name',
  status: TestEntryStatus.start,  // or success, failure, skip
  error: 'Error message if failed',
)

​
Step Entry

StepEntry(
  action: 'tap on button',
  status: StepEntryStatus.start,  // or success, failure
  data: {'key': 'value'},  // Optional metadata
)

​
Log Entry

LogEntry(
  message: 'Custom log message',
)

​
Error Entry

ErrorEntry(
  message: 'Error description',
  stackTrace: 'Stack trace string',
)

​
Platform-Specific Logs

Patrol automatically parses platform-specific log formats:
Patrol captures Flutter logs from logcat with the pattern:
I flutter : <log message>
Captures logs from the iOS console:
(Flutter) flutter: <log message>
Release mode uses a simpler format:
flutter: <log message>
Captures Playwright logs for web testing:
Playwright: <log message>

​
Troubleshooting

Ensure you’re running tests with patrol test or patrol develop, not flutter test. Patrol CLI is required for log capture.
Use --clear-test-steps to automatically remove successful step logs, or --no-test-steps to hide them entirely.
Add the --verbose flag to patrol test to enable Flutter framework logging.
Failed tests are listed in the summary with their full file paths. Look for the ❌ section in the test summary.

​
Best Practices

1

Keep test steps visible during development

Don’t hide test steps while developing tests. They provide valuable debugging information.
2

Use clear test steps in CI

In CI environments, use --clear-test-steps to reduce log output while preserving failure information.
3

Add custom logs for complex tests

Use Patrol’s logging to add context to complex test scenarios:
patrolTest('complex test', ($) async {
  $.log('Starting login flow');
  await $(#emailField).enterText('[email protected]');
  
  $.log('Submitting credentials');
  await $(#loginButton).tap();
});
4

Check the test summary

Always review the test summary for execution time and failure patterns.

​
Next Steps

VS Code Extension

View logs in real-time with the VS Code extension.

CI Configuration

Configure logging for CI environments.

Debugging Tests

Learn advanced debugging techniques.

Writing Tests

Start writing Patrol tests.

​
Package Information

Package: patrol_logVersion: 0.7.1Repository: GitHubPub.dev: patrol_log

Build docs developers (and LLMs) love

Get started for freeTalk to us