testing/ny_testing library

Nylo Testing Framework

A comprehensive testing framework for Nylo with PHPUnit/Pest-like syntax, automatic mocking, time travel, factories, and test isolation.

Quick Start

import 'package:nylo_support/testing/ny_testing.dart';

void main() {
  NyTest.init();

  nySetUpAll(() async {
    NyEnvRegistry.register(getter: Env.get);
    await setupApplication(providers);
  });

  nyGroup('HomePage', () {
    nyWidgetTest('displays content', (tester) async {
      // Use the pumpNyWidget extension for easy widget testing
      await tester.pumpNyWidget(HomePage());
      expect(find.text('Welcome'), findsOneWidget);
    });

    // Or use pumpNyWidgetSimple to avoid font issues completely
    nyWidgetTest('displays links', (tester) async {
      await tester.pumpNyWidgetSimple(HomePage());
      expect(find.text('Documentation'), findsOneWidget);
    });
  });

  nyTest('user can login', () async {
    NyTest.actingAs(User(id: 1, name: 'Test'));
    expectAuthenticated<User>();
  });

  nyTest('can time travel', () async {
    NyTest.travel(DateTime(2025, 1, 1));
    expect(NyTime.now().year, 2025);
    NyTest.travelBack();
  });

  nyTest('mock API responses', () async {
    NyMockApi.respond('/users/*', {'id': 1, 'name': 'John'});
    NyMockApi.respond('/posts/**', {'posts': []});
  });

  nyTest('use factories', () async {
    NyFactory.define<User>((faker) => User(
      name: faker.name(),
      email: faker.email(),
    ));

    final users = NyFactory.create<User>(count: 5);
    expect(users.length, 5);
  });
}

Features

Widget Testing: Easy testing of NyStatefulWidget, NyPage, and NyState
Google Fonts Handling: Automatic configuration to prevent HTTP errors
Test Isolation: Each test runs in isolation with automatic cleanup
Time Travel: Freeze and manipulate time with NyTime
API Mocking: Mock API responses with wildcards using NyMockApi
Factories: Create test data with NyFactory and NyFaker
Authentication: Test as authenticated user with NyTest.actingAs
Assertions: Custom assertions for routes, backpack, locale, and more
Debugging: Use NyTest.dump and NyTest.dd to inspect test state

Classes

ApiCallInfo: Public info about an API call for assertions.
FactoryDefinition<T>: Factory definition container.
FactoryDefinitionWithOverrides<T>: Factory definition with overrides support.
FactoryState<T>: Factory state modifier container.
MockApiRequest: Represents a mock API request.
MockResponse: Represents a mock API response.
NyFactory: Laravel-style model factories for testing.
NyFaker: Faker class for generating random test data.
NyMockApi: API mocking utilities for testing.
NyMockChannels: Auto-mocking for common Flutter platform channels used in Nylo.
NyMockRouteGuard: A mock route guard for testing NyPage route guard behavior.
NyStateTestHelpers: Helpers for testing EventBus-driven state management in NyPage and NyState.
NyTest: Main testing orchestrator for Nylo testing framework.
NyTestCache: In-memory cache implementation for testing.
NyTime: NyTime - Time manipulation utilities for testing.
NyToastRecorder: A simple recorder that tracks toast notifications shown during tests.
NyWidgetTest: Widget testing utilities for Nylo applications.
ToastRecord: A recorded toast notification entry.

Mixins

NyPageTestMixin: Mixin for testing NyState and NyPage widgets.

Extensions

NyWidgetTesterExtension on WidgetTester: Extension on WidgetTester for Nylo-specific widget testing.

Functions

apiWasCalled(String endpoint, {String? method, int? times}) → Matcher: Custom matcher for API calls.
backpackHas(String key, {dynamic value}) → Matcher: Custom matcher for Backpack containing key.
expectApiCalled(String endpoint, {String? method, int? times}) → void: Assert that an API endpoint was called.
expectApiNotCalled(String endpoint, {String? method}) → void: Assert that an API endpoint was not called.
expectAuthenticated<T>() → void: Assert that a user is authenticated.
expectBackpackContains(String key, {dynamic value}) → void: Assert that Backpack contains a specific key.
expectBackpackNotContains(String key) → void: Assert that Backpack does not contain a specific key.
expectDebugMode() → void: Assert that Nylo is in debug mode.
expectDevelopingMode() → void: Assert that Nylo is in developing mode.
expectEnv(String key, dynamic expectedValue) → void: Assert that an environment variable has a specific value.
expectEnvSet(String key) → void: Assert that an environment variable is set (not null).
expectGuest() → void: Assert that no user is authenticated (guest).
expectLoadingNamed(WidgetTester tester, Finder finder, String name) → void: Assert that a named loading key is active in a NyPage/NyState widget.
expectLocale(String locale) → void: Assert that the current locale matches.
expectLocked(WidgetTester tester, Finder finder, String name) → void: Assert that a named lock is currently held in a NyPage/NyState widget.
expectNotLoadingNamed(WidgetTester tester, Finder finder, String name) → void: Assert that a named loading key is not active in a NyPage/NyState widget.
expectNotLocked(WidgetTester tester, Finder finder, String name) → void: Assert that a named lock is not held in a NyPage/NyState widget.
expectNoToastShown({String? id, String? description}) → void: Assert that no toast notification was shown matching the criteria.
expectNotRoute(String route) → void: Assert that the current route is not the specified route.
expectNyloInitialized() → void: Assert that Nylo is initialized.
expectProductionMode() → void: Assert that Nylo is in production mode.
expectRoute(String route) → void: Test helper utilities for Nylo testing.
expectRouteExists(String route) → void: Assert that a route exists in the router.
expectRouteInHistory(String route) → void: Assert that the route history contains a specific route.
expectRoutesExist(List<String> routes) → void: Assert that routes exist in the router.
expectStateAction(String stateName, String action, {int? times}) → void: Assert that a state action was fired to the given stateName.
expectStateData(WidgetTester tester, Finder finder, dynamic matcher) → void: Assert the stateData of a NyPage or NyState widget.
expectStateUpdated(String stateName, {int? times}) → void: Assert that a state update was fired to the given stateName.
expectTestMode() → void: Assert that Nylo is in test mode.
expectToastShown({String? id, String? description}) → void: Assert that a toast notification was shown.
fireStateAction(String stateName, String action, {dynamic data}) → void: Fire a state action to a widget identified by stateName.
fireStateUpdate(String stateName, {dynamic data}) → void: Fire an UpdateState event to a widget identified by stateName.
hasRouteName(String name) → Matcher: Custom matcher for route name.
isType<T>() → TypeMatcher<T>: Matcher for checking if an object is of a specific type.
nyCi(String description, Future<void> callback()) → void: Run a test only in CI environment.
nyFailing(String description, Future<void> callback()) → void: Mark a test as expected to fail.
nyGroup(String description, void callback()) → void: Pest-style group wrapper.
nySetUp(void callback()) → void: Execute a callback before each test in the current group.
nySetUpAll(void callback()) → void: Execute a callback once before all tests in the current group.
nySkip(String description, Future<void> callback(), String reason) → void: Skip a test with a reason.
nyTearDown(void callback()) → void: Execute a callback after each test in the current group.
nyTearDownAll(void callback()) → void: Execute a callback once after all tests in the current group.
nyTest(String description, Future<void> callback(), {bool skip = false, dynamic tags, Timeout? timeout}) → void: Pest-style test wrapper for Nylo tests.
nyWidgetTest(String description, Future<void> callback(WidgetTester tester), {bool skip = false, dynamic tags, Timeout? timeout}) → void: Pest-style widget test wrapper with Patrol integration.
testNyPage(String description, {required Widget build(), required Future<void> expectations(WidgetTester tester), bool useSimpleTheme = true, Duration initTimeout = const Duration(seconds: 10), bool skip = false}) → void: Test a NyStatefulWidget page with common assertions.
testNyPageLoading(String description, {required Widget build(), bool skip = false}) → void: Test a NyStatefulWidget's loading state.

Typedefs

MockApiHandler = Future Function(MockApiRequest request): Handler function type for mock API responses.

testing/ny_testing library

Quick Start

Features

Classes

Mixins

Extensions

Functions

Typedefs

nylo_support package

ny_testing library