Imagine you're building a Flutter app, and you want to ensure it's easy for everyone to use, including those who rely on screen readers or require larger text. Generating reports helps you spot issues early. We'll walk through this step by step, like we're sitting together at your desk, opening code and running commands.
Prerequisites
Before diving in, check a few basics to avoid hiccups. You need Flutter installed; run flutter doctor in your terminal to confirm everything works, like your Android or iOS setup. Make sure your app project is ready; open it in your code editor, such as VS Code. You'll also need the Axe Flutter package, which scans for accessibility problems. Add it to your pubspec.yaml file under dependencies like this:
dependencies:
axe_flutter: ^0.1.0In your terminal, type flutter pub get to pull it in. If you're testing on a device, connect an emulator or phone with accessibility turned on, like TalkBack for Android. This setup takes about five minutes and ensures your scans run smoothly.
Adding Axe to Your Tests
Now, let's bring Axe into your app's tests. Open your test folder and create a new file, say accessibility_test.dart. At the top, import the tools you need:
import 'package:flutter_test/flutter_test.dart';
import 'package:axe_flutter/axe_flutter.dart';
import 'package:your_app/main.dart'; // Replace with your app's main file
In the test, pump your app widget and run the scan. Here's a simple example:
void main() {
testWidgets('Check app for accessibility issues', (WidgetTester tester) async {
await tester.pumpWidget(MyApp());
final results = await axeFlutter.testrun(tester, 'My accessibility scan');
expect(results.violations, isEmpty); // This fails if issues are found
});
}This code loads your app and checks it against rules for things like button labels or color contrast. Run it with flutter test in the terminal. If violations show up, Axe lists them clearly, like “Button missing a description.”
Running the Scan and Capturing Data
With the test in place, execute it to generate raw data. In your terminal, navigate to your project and run flutter test accessibility_test.dart. Axe will output details right there; things like which widget failed and why, tied to simple rules from accessibility standards.
To save this as a report, modify your test to export the results. Add code to write to a file:
import 'dart:io';
import 'dart:convert';
// Inside your test, after the scan:
final report = jsonEncode({
'violations': results.violations.map((v) => v.toJson()).toList(),
'passes': results.passes.map((p) => p.toJson()).toList(),
'timestamp': DateTime.now().toIso8601String(),
});
await File('accessibility_report.json').writeAsString(report);Run the test again, and now you have a JSON file in your project root. Open it in a text editor to see the structure: violations include the rule broken, the element involved, and fix suggestions, all in plain text.
Turning Data into Readable Reports
JSON is great for machines, but you want something easy to share. Let's create a human-friendly HTML report. Install a simple tool like dart pub global activate html if needed, but for basics, use Dart's built-in features or a package like html.
Create another Dart script, generate_report.dart, in your project:
import 'dart:io';
import 'dart:convert';
import 'package:html/parser.dart' show parse;
import 'package:html/writer.dart' show writeHtmlString; // Add html package if using
void main() async {
final jsonString = await File('accessibility_report.json').readAsString();
final data = jsonDecode(jsonString);
// Build HTML string
String html = '''
<!DOCTYPE html>
<html>
<head><title>Flutter Accessibility Report</title></head>
<body>
<h1>Accessibility Scan Results</h1>
<p>Run on: ${data['timestamp']}</p>
<h2>Issues Found</h2>
<ul>
''';
for (var violation in data['violations']) {
html += '<li>${violation['description']} - Fix: ${violation['help']}</li>';
}
html += '''
</ul>
<h2>Good Parts</h2>
<ul>
''';
for (var pass in data['passes']) {
html += '<li>${pass['description']}</li>';
}
html += '</ul></body></html>';
await File('accessibility_report.html').writeAsString(html);
print('Report saved as accessibility_report.html');
}
Run dart run generate_report.dart. Open the HTML file in your browser; it shows issues in a list, with fixes next to them. For example, if a text field lacks a label, it'll say "Add a label to this input for screen readers" and point to the code line.
Customizing Reports for Your Team
Tailor the report to fit your needs. If you want images, add screenshots during tests using tester.takeScreenshot(). Save them and link in the HTML, like <img src="screenshot.png" alt="Widget with issue">.
For ongoing checks, hook this into your build process. In pubspec.yaml, add a script under scripts, or use a CI tool like GitHub Actions. Create a YAML file in .github/workflows/:
name: Accessibility Report
on: [push]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: subosito/flutter-action@v2
- run: flutter pub get
- run: flutter test accessibility_test.dart
- run: dart run generate_report.dart
- uses: actions/upload-artifact@v2
with:
name: accessibility-report
path: accessibility_report.htmlPush your code, and the report uploads automatically. Download it from the workflow to review changes over time.
Checking and Fixing Based on the Report
Open your report and go through each issue one by one. For a missing label, wrap the widget in Flutter's Semantics:
Semantics(
label: 'Search button',
child: ElevatedButton(onPressed: search, child: Text('Search')),
)Re-run the test and regenerate the report. The issue should disappear. Track progress by comparing old and new JSON files; count violations to see improvement. It will keep your app accessible without extra hassle. Regularly run scans, fix as you go, and share reports to build better apps together.