Fully support multiple nested ContextPlus.root?

[passsy]

We want to use context plus for dependency injection in tests.

We have one MyApp widget and want to inject a either use a ProdApi or a FakeApi class.

// Sample without dependency injection

import 'package:context_plus/context_plus.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

final Ref<Api> apiRef = Ref<Api>();

abstract class Api {
  Future<void> sendHeartbeat();
}

class ProdApi implements Api {
  @override
  Future<void> sendHeartbeat() async {
    // Simulate sending a heartbeat to the production server
    print('Heartbeat sent to production server');
  }
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return ContextPlus.root(
      child: Builder(builder: (context) {
        apiRef.bind(context, () => ProdApi());
        return MaterialApp(
          home: HomeScreen(),
        );
      }),
    );
  }
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({
    super.key,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Sample App'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            ElevatedButton(
              onPressed: () {
                apiRef.of(context).sendHeartbeat();
              },
              child: const Text('Send to Server'),
            ),
          ],
        ),
      ),
    );
  }
}

Currently, ContextPlus.root lives within MyApp. This is fine for production, but we can't inject from the outside in our test environment

class FakeApi implements Api {
  @override
  Future<void> sendHeartbeat() async {
    throw Exception('cannot reach server');
  }
}

void main() {
  testWidgets('send heartbeat to server', (tester) async {
    final app = Builder(builder: (context) {
      // Fails with "No ContextRef.root() found. Did you forget to add a ContextRef.root() widget?"
      apiRef.bind(context, () => FakeApi());
      return const MyApp();
    });
    await tester.pumpWidget(app);
  });
}

There are two ways to solve this

Move ContextRef.root

Remove ContextPlus.root and dependencies from MyApp and move it up to the main function

void main() {
  runApp(ContextPlus.root(
    child: Builder(
      builder: (context) {
        apiRef.bind(context, () => ProdApi());
        return MyApp();
      },
    ),
  ));
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomeScreen(),
    );
  }
}

Add ContextPlus.root in the test

void main() {
  testWidgets('send heartbeat to server', (tester) async {
    final app = ContextPlus.root(
      child: Builder(builder: (context) {
        apiRef.bind(context, () => FakeApi());
        return const MyApp();
      }),
    );
    await tester.pumpWidget(app);
  });
}

Wrap with another ContextRef.root

Keep ContextPlus.root in MyApp but use bindWhenUnbound instead of bind.
In tests, add another ContextPlus.root to inject fakes.

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return ContextPlus.root(
      child: Builder(builder: (context) {
        apiRef.bindWhenUnbound(context, () => ProdApi());
        return MaterialApp(
          home: HomeScreen(),
        );
      }),
    );
  }
}

void main() {
  testWidgets('send heartbeat to server', (tester) async {
    final app = ContextPlus.root(
      child: Builder(builder: (context) {
        apiRef.bind(context, () => FakeApi());
        return const MyApp();
      }),
    );
    await tester.pumpWidget(app);
  });
}

extension BindUnboundRef<T> on Ref<T> {
  /// Binds the Ref if it is not already bound to [context], otherwise returns the existing value from [context].
  T bindWhenUnbound(
    BuildContext context,
    T Function() create, {
    void Function(T value)? dispose,
    Object? key,
  }) {
    try {
      T found = of(context);
      return found;
    } catch (e) {
      // If the Ref is not bound, bind it now
      return bind(context, create, dispose: dispose, key: key);
    }
  }
}

---

I do prefer wrapping again with ContextPlus.root and it seems to work fine. But I'm not 100% sure about the internals, if this case is accounted for. I couldn't find tests for this case. That's why I'm coming here to ask if anything could go wrong with nested ContextPlus.root.

In case this is completely fine, I suggest:

• Add test cases for nested ContextPlus.root
• Add an actual Exception like ProviderNotFoundException which I can catch in bindWhenUnbound.

[s0nerik]

Currently, all context_plus-related package tests follow the pattern you've outlined in the "Move ContextRef.root" section.

It seems like you're looking for a way to overwrite a top-level Ref binding with a specific value for tests. Unfortunately, currently, there's no easy-to-use utility for doing this. This is mostly because, similarly to inherited widgets, all Ref.of(context) calls return values bound to the closest parent BuildContext (including the context itself), meaning that each BuildContext can override any existing Ref for its children.

Adding a tests-only Ref.overrideAllBindingsWith(...) feels like the most straightforward way of achieving what you're looking for and the implementation seems trivial, but I'm afraid of it becoming a footgun if this gets used on a Ref that is bound to many differents values throughout the element tree. In a complex enough setup, swapping the value for all of them at the same time may result in weird test results.

What I'm sure will work well (I've used this approach myself in a couple of places) is modifying the MyApp like this:

class MyApp extends StatelessWidget {
- const MyApp({super.key});
+ const MyApp({super.key, this.overrideGlobalRefs});

+ final void Function(BuildContext context)? overrideGlobalRefs;

  @override
  Widget build(BuildContext context) {
    return ContextPlus.root(
      child: Builder(builder: (context) {
        apiRef.bind(context, () => ProdApi());
+       overrideGlobalRefs?.call(context);
        return MaterialApp(
          home: HomeScreen(),
        );
      }),
    );
  }
}

and then using it in the tests like this:

class FakeApi implements Api {
  @override
  Future<void> sendHeartbeat() async {
    throw Exception('cannot reach server');
  }
}

void main() {
  testWidgets('send heartbeat to server', (tester) async {
-    final app = Builder(builder: (context) {
-      // Fails with "No ContextRef.root() found. Did you forget to add a ContextRef.root() widget?"
-      apiRef.bind(context, () => FakeApi());
-      return const MyApp();
-    });
+    final app = MyApp(
+      overrideGlobalRefs: (context) {
+        apiRef.bind(context, () => FakeApi(), allowRebind: true);
+      },
+    );
    await tester.pumpWidget(app);
  });
}

---

Regarding bindWhenUnbound and wrapping with another ContextPlus.root in tests.

Even though there are no tests for this yet, it should work just fine since ContextPlus.root just introduces _InheritedElementDataHolder, InheritedContextRefRoot and InheritedContextWatch inherited widgets into the tree, each of which doesn't depend on any global state for storing and obtaining data.

I'll add tests for nested ContextPlus.root, ContextRef.root, and ContextWatch.root as a reassurance sometime soon.

As for the lack of a special exception for when no provider is available in the context, I believe a better approach would be to update the bindWhenUnbound method to use Ref.maybeOf(context) for checking whether a Ref is bound already or not. This way, try-catch won't be needed:

extension BindUnboundRef<T> on Ref<T> {
  /// Binds the Ref if it is not already bound to [context], otherwise returns the existing value from [context].
  T bindWhenUnbound(
    BuildContext context,
    T Function() create, {
    void Function(T value)? dispose,
    Object? key,
  }) {
    return maybeOf(context) ?? bind(context, create, dispose: dispose, key: key);
  }
}

[passsy]

It seems like you're looking for a way to overwrite a top-level Ref binding with a specific value for tests.

No. I want my app to use the injected Api and create a fallback in case it is not injected.

I'm not looking for any Ref.overrideAllBindingsWith(...). That would make things unnecessary complicated.

We use the "fallback injection pattern" (I just came up with that name) with package:provider for years and just want to use the same injection pattern with context_plus.

    return MultiProvider(
      providers: [
        if (context.watch<Api?>() == null)
          Provider<Api>(create: (_) => ProdApi()),
      ],
    );

---

Nice, I did not find maybeOf because I'm still using context_plus: 4.1.4 with Dart 3.6. Newer versions require Dart 3.7. Was there any particular reason to bump the min Dart/Flutter SDKs?

---

overrideGlobalRefs is an interesting idea. I'd even remove the necessarity for allowRebind by wrapping MaterialApp with one more Builder.

    final app = MyApp(
      overrideGlobalRefs: (context) {
        apiRef.bind(context, () => FakeApi());
      },
    );

We tried it in the past and found some more complex scenarios where it broke for us:

void main() {
  runApp(
    MyApp(
      overrideGlobalRefs: (context) {
        // httpClientRef is only used before `overrideGlobalRefs` was called, injection does not work
        httpClientRef.bind(context, () => FakeHttpClient());
      },
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key, this.overrideGlobalRefs});

  final void Function(BuildContext context)? overrideGlobalRefs;

  @override
  Widget build(BuildContext context) {
    return ContextPlus.root(
      child: Builder(builder: (context) {
        final client = httpClientRef.bind(context, () => HttpClient());
        apiRef.bind(context, () => ProdApi(client: client));
        overrideGlobalRefs?.call(context);
        
        final api = apiRef.of(context);
        // api is ProdApi with HttpClient, not FakeHttpClient!
        return MaterialApp(
          home: HomeScreen(),
        );
      }),
    );
  }
}

There is no "correct" location to call overrideGlobalRefs. At the end, at the start, somewhere in between. There are always cases were it doesn't work. We ran into the same issues with package:provider until we migrated to the "fallback injection pattern"

[s0nerik]

Newer versions require Dart 3.7. Was there any particular reason to bump the min Dart/Flutter SDKs?

Yes, a huge one! Dart 3.7 introduced an improvement to the type inference system, which allowed me to finally make values provided by .watch(), .watchOnly() and .watchEffect() to become intuitive in all cases.

There is no "correct" location to call overrideGlobalRefs. At the end, at the start, somewhere in between. There are always cases were it doesn't work. We ran into the same issues with package:provider until we migrated to the "fallback injection pattern"

Yeah, I see the potential issue here. The "fallback injection" is much less prone to errors introduced by adding new code later, which is great!

So, to reiterate, I believe that wrapping an app widget with another ContextPlus.root and providing fallback bindings there should work just fine, and I like that approach even more than what I've used so far myself. I just need to write the tests for verifying this, which I'll do soon. Other than tests, it seems like the latest version of context_plus covers all you need for implementing this, right?