#20 Update javadoc for withMock() and withSpy()

Author: rbygrave

src/main/java/io/dinject/BootContext.java

@@ -153,38 +153,41 @@ public BootContext withIgnoreMissingModuleDependencies() {
   }
 
   /**
-   * Supply a bean to the context that will be used instead of any similar bean in the context.
+   * Supply a bean to the context that will be used instead of any
+   * similar bean in the context.
    * <p>
-   * This is typically expected to be used in tests and the bean supplied is typically a test double
-   * or mock.
+   * This is typically expected to be used in tests and the bean
+   * supplied is typically a test double or mock.
    * </p>
    *
    * <pre>{@code
    *
-   *   @Test
-   *   public void someComponentTest() {
+   *   Pump pump = mock(Pump.class);
+   *   Grinder grinder = mock(Grinder.class);
    *
-   *     MyRedisApi mockRedis = mock(MyRedisApi.class);
-   *     MyDbApi mockDatabase = mock(MyDbApi.class);
+   *   try (BeanContext context = new BootContext()
+   *     .withBeans(pump, grinder)
+   *     .load()) {
    *
-   *     try (BeanContext context = new BootContext()
-   *       .withBeans(mockRedis, mockDatabase)
-   *       .load()) {
+   *     CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
+   *     coffeeMaker.makeIt();
    *
-   *       // built with test doubles injected ...
-   *       CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
-   *       coffeeMaker.makeIt();
+   *     Pump pump1 = context.getBean(Pump.class);
+   *     Grinder grinder1 = context.getBean(Grinder.class);
    *
-   *       assertThat(...
-   *     }
-   *   }
+   *     assertThat(pump1).isSameAs(pump);
+   *     assertThat(grinder1).isSameAs(grinder);
    *
+   *     verify(pump).pumpWater();
+   *     verify(grinder).grindBeans();
+   *   }
    *
    * }</pre>
    *
    * @param beans The bean used when injecting a dependency for this bean or the interface(s) it implements
    * @return This BootContext
    */
+  @SuppressWarnings("unchecked")
   public BootContext withBeans(Object... beans) {
     for (Object bean : beans) {
       suppliedBeans.add(new SuppliedBean(suppliedType(bean.getClass()), bean));
@@ -198,6 +201,25 @@ public BootContext withBeans(Object... beans) {
    * This is typically a test double often created by Mockito or similar.
    * </p>
    *
+   * <pre>{@code
+   *
+   *   try (BeanContext context = new BootContext()
+   *     .withBean(Pump.class, mock)
+   *     .load()) {
+   *
+   *     Pump pump = context.getBean(Pump.class);
+   *     assertThat(pump).isSameAs(mock);
+   *
+   *     // act
+   *     CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
+   *     coffeeMaker.makeIt();
+   *
+   *     verify(pump).pumpSteam();
+   *     verify(pump).pumpWater();
+   *   }
+   *
+   * }</pre>
+   *
    * @param type The dependency injection type this bean is target for
    * @param bean The supplied bean instance to use (typically a test mock)
    */
@@ -208,31 +230,116 @@ public <D> BootContext withBean(Class<D> type, D bean) {
 
   /**
    * Use a mockito mock when injecting this bean type.
+   *
+   * <pre>{@code
+   *
+   *   try (BeanContext context = new BootContext()
+   *     .withMock(Pump.class)
+   *     .withMock(Grinder.class, grinder -> {
+   *       // setup the mock
+   *       when(grinder.grindBeans()).thenReturn("stub response");
+   *     })
+   *     .load()) {
+   *
+   *
+   *     CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
+   *     coffeeMaker.makeIt();
+   *
+   *     // this is a mockito mock
+   *     Grinder grinder = context.getBean(Grinder.class);
+   *     verify(grinder).grindBeans();
+   *   }
+   *
+   * }</pre>
    */
   public <D> BootContext withMock(Class<D> type) {
-    suppliedBeans.add(new SuppliedBean<>(type, null, null));
-    return this;
+    return withMock(type, null);
   }
 
   /**
-   * Use a mockito mock when injecting this bean type additionally running setup on the mock instance.
+   * Use a mockito mock when injecting this bean type additionally
+   * running setup on the mock instance.
+   *
+   * <pre>{@code
+   *
+   *   try (BeanContext context = new BootContext()
+   *     .withMock(Pump.class)
+   *     .withMock(Grinder.class, grinder -> {
+   *
+   *       // setup the mock
+   *       when(grinder.grindBeans()).thenReturn("stub response");
+   *     })
+   *     .load()) {
+   *
+   *
+   *     CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
+   *     coffeeMaker.makeIt();
+   *
+   *     // this is a mockito mock
+   *     Grinder grinder = context.getBean(Grinder.class);
+   *     verify(grinder).grindBeans();
+   *   }
+   *
+   * }</pre>
    */
   public <D> BootContext withMock(Class<D> type, Consumer<D> consumer) {
     suppliedBeans.add(new SuppliedBean<>(type, null, consumer));
     return this;
   }
 
-
   /**
    * Use a mockito spy when injecting this bean type.
+   *
+   * <pre>{@code
+   *
+   *   try (BeanContext context = new BootContext()
+   *     .withSpy(Pump.class)
+   *     .load()) {
+   *
+   *     // setup spy here ...
+   *     Pump pump = context.getBean(Pump.class);
+   *     doNothing().when(pump).pumpSteam();
+   *
+   *     // act
+   *     CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
+   *     coffeeMaker.makeIt();
+   *
+   *     verify(pump).pumpWater();
+   *     verify(pump).pumpSteam();
+   *   }
+   *
+   * }</pre>
    */
   public <D> BootContext withSpy(Class<D> type) {
-    enrichBeans.add(new EnrichBean<>(type, null));
-    return this;
+    return withSpy(type, null);
   }
 
   /**
-   * Use a mockito spy when injecting this bean type additionally running setup on the spy instance.
+   * Use a mockito spy when injecting this bean type additionally
+   * running setup on the spy instance.
+   *
+   * <pre>{@code
+   *
+   *   try (BeanContext context = new BootContext()
+   *     .withSpy(Pump.class, pump -> {
+   *       // setup the spy
+   *       doNothing().when(pump).pumpWater();
+   *     })
+   *     .load()) {
+   *
+   *     // or setup here ...
+   *     Pump pump = context.getBean(Pump.class);
+   *     doNothing().when(pump).pumpSteam();
+   *
+   *     // act
+   *     CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
+   *     coffeeMaker.makeIt();
+   *
+   *     verify(pump).pumpWater();
+   *     verify(pump).pumpSteam();
+   *   }
+   *
+   * }</pre>
    */
   public <D> BootContext withSpy(Class<D> type, Consumer<D> consumer) {
     enrichBeans.add(new EnrichBean<>(type, consumer));

src/test/java/org/example/coffee/BootContextAddTest.java

@@ -6,6 +6,7 @@
 import org.mockito.Mockito;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.verify;
 
 public class BootContextAddTest {
 
@@ -76,6 +77,10 @@ public void withMockitoMock_expect_mockUsed() {
 
       CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
       assertThat(coffeeMaker).isNotNull();
+      coffeeMaker.makeIt();
+
+      verify(pump).pumpSteam();
+      verify(pump).pumpWater();
     }
   }
 

src/test/java/org/example/coffee/BootContext_mockitoSpyTest.java

@@ -9,10 +9,36 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.doNothing;
+import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
 
 public class BootContext_mockitoSpyTest {
 
+  @Test
+  public void withBeans_asMocks() {
+
+    Pump pump = mock(Pump.class);
+    Grinder grinder = mock(Grinder.class);
+
+    try (BeanContext context = new BootContext()
+      .withBeans(pump, grinder)
+      .load()) {
+
+      CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
+      coffeeMaker.makeIt();
+
+      Pump pump1 = context.getBean(Pump.class);
+      Grinder grinder1 = context.getBean(Grinder.class);
+
+      assertThat(pump1).isSameAs(pump);
+      assertThat(grinder1).isSameAs(grinder);
+
+      verify(pump).pumpWater();
+      verify(grinder).grindBeans();
+    }
+  }
+
   @Test
   public void withMockitoSpy_noSetup_expect_spyUsed() {
 
@@ -58,34 +84,41 @@ public void withMockitoSpy_expect_spyUsed() {
       })
       .load()) {
 
+      // or setup here ...
       Pump pump = context.getBean(Pump.class);
+      doNothing().when(pump).pumpSteam();
 
+      // act
       CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
-      assertThat(coffeeMaker).isNotNull();
       coffeeMaker.makeIt();
 
       verify(pump).pumpWater();
+      verify(pump).pumpSteam();
     }
   }
 
   @Test
   public void withMockitoMock_expect_mockUsed() {
 
-    AtomicReference<Pump> mock = new AtomicReference<>();
+    AtomicReference<Grinder> mock = new AtomicReference<>();
 
     try (BeanContext context = new BootContext()
-      .withMock(Grinder.class)
-      .withMock(Pump.class, pump -> {
-        // do something interesting to setup the mock
-        mock.set(pump);
+      .withMock(Pump.class)
+      .withMock(Grinder.class, grinder -> {
+        // setup the mock
+        when(grinder.grindBeans()).thenReturn("stub response");
+        mock.set(grinder);
       })
       .load()) {
 
-      Pump pump = context.getBean(Pump.class);
-      assertThat(pump).isSameAs(mock.get());
+      Grinder grinder = context.getBean(Grinder.class);
+      assertThat(grinder).isSameAs(mock.get());
 
       CoffeeMaker coffeeMaker = context.getBean(CoffeeMaker.class);
       assertThat(coffeeMaker).isNotNull();
+      coffeeMaker.makeIt();
+
+      verify(grinder).grindBeans();
     }
   }
 

src/test/java/org/example/coffee/CoffeeMaker.java

@@ -1,6 +1,5 @@
 package org.example.coffee;
 
-import io.dinject.ContextModule;
 import org.example.coffee.grind.Grinder;
 
 import javax.inject.Singleton;
@@ -20,7 +19,7 @@ public CoffeeMaker(Pump pump, Grinder grinder) {
 
   public String makeIt() {
     System.out.println("making it ...");
-    grinder.grindBeans();
+    System.out.println("grinder:" + grinder.grindBeans());
     pump.pumpWater();
     pump.pumpSteam();
     System.out.println("Done");