Testing
Test code that sends analytics with Analytics.fake(), which records what passed validation, scrubbing and the opt-out gate, with no live property.
On this page
Quick Reference#
| You want to check | Use |
|---|---|
| An event was sent | fake.assertTracked('name') |
| An event was not sent | fake.assertNotTracked('name') |
| Nothing reached the driver | fake.assertNothingSent() |
| Which events were sent | fake.events |
| Which page views were sent | fake.screens |
| The identity at each call | RecordedAnalyticsCall.userId, userProperties, defaultParams |
No mocking library is needed: the package fakes through contract inheritance.
Faking the Facade#
Analytics.fake() binds the real AnalyticsManager over a FakeAnalytics driver and returns the driver. Validation, scrubbing, opt-out and reset apply exactly as in the app, and the fake records what reached the driver.
import 'package:flutter_test/flutter_test.dart';
import 'package:magic/magic.dart';
import 'package:magic_analytics/magic_analytics.dart';
void main() {
setUp(() {
MagicApp.reset();
Magic.flush();
});
tearDown(() {
Analytics.unfake();
MagicRouter.reset();
});
test('creating a monitor sends one event', () async {
final FakeAnalytics fake = Analytics.fake();
await Analytics.track('monitor_created', {'monitor_type': 'http'});
fake.assertTracked('monitor_created');
expect(fake.events.single.parameters, {'monitor_type': 'http'});
});
}
Analytics.unfake() removes the fake; the next call resolves the provider's binding again. Call Analytics.fake() after the provider registers, because register() binds a real manager that would replace a fake bound earlier.
Widget Tests#
In a testWidgets body, call Analytics.fake() inside the body, not in setUp. The manager's send queue has to be created in the widget test's fake-async zone for a pump to drain it:
import 'package:flutter/widgets.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:magic/magic.dart';
import 'package:magic_analytics/magic_analytics.dart';
void main() {
tearDown(() {
Analytics.unfake();
MagicRouter.reset();
});
testWidgets('the page view carries the pattern, never the id', (
tester,
) async {
final FakeAnalytics fake = Analytics.fake();
MagicRoute.page('/', () => const SizedBox());
MagicRoute.page('/monitors/:id', () => const SizedBox());
MagicRouter.instance.addObserver(AnalyticsNavigatorObserver());
await tester.pumpWidget(
WidgetsApp.router(
color: const Color(0xFF000000),
routerConfig: MagicRouter.instance.routerConfig,
),
);
await tester.pumpAndSettle();
MagicRouter.instance.to('/monitors/4711');
await tester.pumpAndSettle();
expect(fake.screens.last.name, '/monitors/:id');
expect(fake.screens.toString(), isNot(contains('4711')));
});
}
A call made without await (an auth listener, the observer) lands on a later microtask, so await Future<void>.delayed(Duration.zero) before you read the record in a plain test.
Reading the Record#
Each RecordedAnalyticsCall has a kind (RecordedCallKind), a name, its parameters and a copy of the identity the transport held when the call arrived, so a test can prove which user and which team facts an event carried. FakeAnalytics also exposes the live userId, userProperties, defaultParams, optedOut and calls; set clientIdValue to fake Analytics.clientId().
import 'package:flutter_test/flutter_test.dart';
import 'package:magic_analytics/magic_analytics.dart';
void main() {
test('team facts ride on the event, the user stays user-level', () async {
final FakeAnalytics fake = Analytics.fake();
await Analytics.identify('user-a');
await Analytics.setDefaultParams({'team_plan': 'pro'});
await Analytics.track('monitor_created');
final RecordedAnalyticsCall event = fake.events.single;
expect(event.userId, 'user-a');
expect(event.defaultParams, {'team_plan': 'pro'});
expect(event.userProperties, isEmpty);
});
}
Gotchas#
| Mistake | Fix |
|---|---|
Calling Analytics.fake() before the provider registers |
Fake after register(), or the real manager replaces the fake |
Faking in setUp of a testWidgets test |
Call Analytics.fake() inside the test body |
| Leaving the fake bound after a test | Analytics.unfake() in tearDown |
| A route that outlives its test | MagicRouter.reset() in tearDown |
| An event that never shows up | A limit was broken: debug fails an assert, release drops the call; check the name and the values |
| Asserting on a call made while opted out | An opted-out manager reaches no driver, so the fake records nothing |
Related Documentation#
- Facade and Provider: the limits a test trips over.
- Consent and Opt-Out: what an opted-out device records.