added javadoc and other comments

src/main/java/nl/sander/testautomation/cars/Car.java

@@ -2,6 +2,9 @@ package nl.sander.testautomation.cars;
 
 import java.util.Objects;
 
+/**
+ * Part of ultra simple Car application
+ */
 public class Car {
 
     private long id;

src/main/java/nl/sander/testautomation/cars/CarDao.java

@@ -3,6 +3,9 @@ package nl.sander.testautomation.cars;
 import java.sql.SQLException;
 import java.util.List;
 
+/**
+ * Part of ultra simple Car application
+ */
 public interface CarDao {
 
     Car getCar(long carId) throws SQLException;

src/main/java/nl/sander/testautomation/cars/CarModule.java

@@ -2,6 +2,9 @@ package nl.sander.testautomation.cars;
 
 import com.google.inject.AbstractModule;
 
+/**
+ * Part of ultra simple Car application
+ */
 public class CarModule extends AbstractModule {
 
     @Override

src/main/java/nl/sander/testautomation/cars/CarService.java

@@ -4,6 +4,9 @@ import javax.inject.Inject;
 import java.sql.SQLException;
 import java.util.Optional;
 
+/**
+ * Part of ultra simple Car application
+ */
 public class CarService {
 
     @Inject

src/main/java/nl/sander/testautomation/cars/JdbcCarDao.java

@@ -10,6 +10,9 @@ import java.sql.SQLException;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Part of ultra simple Car application
+ */
 public class JdbcCarDao implements CarDao {
 
     @Inject

src/main/java/nl/sander/testautomation/database/Database.java

@@ -4,6 +4,9 @@ import java.sql.Connection;
 import java.sql.DriverManager;
 import java.sql.SQLException;
 
+/**
+ * Part of ultra simple Car application
+ */
 public class Database {
 
     private final Connection connection;

src/test/java/nl/sander/testautomation/CucumberTests.java

@@ -4,6 +4,9 @@ import io.cucumber.junit.Cucumber;
 import io.cucumber.junit.CucumberOptions;
 import org.junit.runner.RunWith;
 
+/**
+ * Example CucumberRunner
+ */
 @RunWith(Cucumber.class)
 @CucumberOptions(
         strict = true,

src/test/java/nl/sander/testautomation/Mode.java

@@ -1,5 +1,8 @@
 package nl.sander.testautomation;
 
+/**
+ * set by the framework driven by cucumber tags. Limited for now
+ */
 public enum Mode {
     UNIT_TEST,
     UNIT_INTEGRATION_TEST,

src/test/java/nl/sander/testautomation/UnitTest.java

@@ -11,16 +11,32 @@ public interface UnitTest {
     Injector injector = Guice.createInjector(
             override(new CarModule()).with(new UnitTestModule()));
 
+    /**
+     * Unittest must call this to get a real (unmocked) instance that can be tested.
+     * Any dependencies that can be found in a guice module will be injected.
+     *
+     * For now the instance class must have a default constructor.
+     * @param type the type of the class
+     * @param <T> generic
+     * @return an instance of the specified class
+     */
     default <T> T classToTest(Class<T> type) {
         try {
             T instance = type.newInstance();
             injector.injectMembers(instance);
             return instance;
         } catch (InstantiationException | IllegalAccessException e) {
-            throw new RuntimeException(e);
+            throw new RuntimeException(e); //TODO create descriptive exception
         }
     }
 
+    /**
+     * looks up a mock from the guice module.
+     *
+     * @param type The type of the mock
+     * @param <T> The generic type of the mock
+     * @return A mocked instance of the given type.
+     */
     default <T> T mock(Class<T> type) {
         return injector.getInstance(type);
     }

src/test/java/nl/sander/testautomation/UnitTestModule.java

@@ -8,7 +8,7 @@ import org.reflections.util.ClasspathHelper;
 import org.reflections.util.ConfigurationBuilder;
 
 /**
- * mocks all classes in the SUT
+ * Mocks all classes in the SUT.
  *
  * Works but could be optimized by only searching for types/annotations
  */

src/test/java/nl/sander/testautomation/steps/StepDefinitions.java

@@ -4,6 +4,9 @@ package nl.sander.testautomation.steps;
 import io.cucumber.java.Before;
 import nl.sander.testautomation.Mode;
 
+/**
+ * Common stepdefinitions. Used to derive behavior from tags
+ */
 public class StepDefinitions {
 
     public static Mode testMode;

src/test/java/nl/sander/testautomation/steps/cars/DatabaseStepDefinitions.java

@@ -22,6 +22,9 @@ import java.util.stream.Collectors;
 
 import static org.junit.Assert.assertTrue;
 
+/**
+ * Example stepdefinitions for our car application
+ */
 public class DatabaseStepDefinitions implements En {
 
     private CarDao carDao;
@@ -41,13 +44,14 @@ public class DatabaseStepDefinitions implements En {
         });
 
         Then("^a new car is added to the inventory$", (DataTable dataTable) -> {
+            if (StepDefinitions.testMode == Mode.DATABASE_INTEGRATION_TEST) {
                 Map<Long, Car> carRecordsById = this.carDao.getAllCars().stream().collect(Collectors.toMap(Car::getId, Function.identity()));
                 dataTable.asMaps().stream()
                         .map(record -> Long.parseLong(record.get("id")))
                         .forEach(carId -> {
                             assertTrue(String.format("car with id %s not found", carId), carRecordsById.containsKey(carId));
                         });
-
+            }
         });
     }
 

src/test/java/nl/sander/testautomation/tests/cars/CarServiceTest.java

@@ -1,9 +1,9 @@
 package nl.sander.testautomation.tests.cars;
 
+import nl.sander.testautomation.UnitTest;
 import nl.sander.testautomation.cars.Car;
 import nl.sander.testautomation.cars.CarDao;
 import nl.sander.testautomation.cars.CarService;
-import nl.sander.testautomation.UnitTest;
 import org.junit.Test;
 
 import java.sql.SQLException;
@@ -13,9 +13,16 @@ import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertTrue;
 import static org.mockito.Mockito.*;
 
+/**
+ * Example for a pure unit test
+ */
 public class CarServiceTest implements UnitTest {
 
-    private final CarDao carDao = mock(CarDao.class);
+    /* lookup mock from guice injector. This is only to set the When for this test */
+    private final CarDao carDao = mock(CarDao.class); //TODO we might be able to use the @Mock annotation to do the same
+
+    /* lookup actual instance. All dependencies with @Inject are automatically injected with mocks */
+    //TODO we might be able to use the @InjectMocks annotation to do the same
     private final CarService carService = classToTest(CarService.class);
 
     @Test

src/test/java/nl/sander/testautomation/tests/cars/new_car.feature

@@ -1,5 +1,7 @@
+#Example cucumber test.
 Feature: car module
 
+  #In this scenario a h2 database is used to test database integration
   @DatabaseIntegrationTest
   Scenario: add new car
     When a user enters a car with id 1: a red volkswagen kever, built in 1967