wip

Author: igorbernstein2

TESTING.md

@@ -3,6 +3,7 @@
 This library provides tools to help write tests for code that uses the following google-cloud services:
 
 -  [BigQuery](#testing-code-that-uses-bigquery)
+-  [Bigtable](#testing-code-that-uses-bigtable)
 -  [Compute](#testing-code-that-uses-compute)
 -  [Datastore](#testing-code-that-uses-datastore)
 -  [DNS](#testing-code-that-uses-dns)
@@ -41,6 +42,24 @@ Here is an example that clears the dataset created in Step 3.
   RemoteBigQueryHelper.forceDelete(bigquery, dataset);
   ```
 
+### Testing code that uses Bigtable
+
+Bigtable integration tests can either be run against an emulator or a real Bigtable table. The
+target environment can be selected via the `bigtable.env` system property. By default it is set to
+`emulator` and the other option is `prod`.
+
+To use the `emulator` environment, please install the gcloud sdk and use it to install the
+`cbtemulator` via `gcloud components install bigtable`.
+
+To use the `prod` environment:
+1. Create a table with a column family named `cf`.
+2. Download the [JSON service account credentials file][create-service-account] from the Google 
+   Developer's Console.
+3. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the credentials file
+4. Set the system properties `bigtable.project`, `bigtable.instance` and `bigtable.table` to the
+   table you created earlier.
+
+
 ### Testing code that uses Compute
 
 Currently, there isn't an emulator for Google Compute, so an alternative is to create a test

google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/data/v2/it/env/Emulator.java

@@ -34,8 +34,11 @@
 import java.io.InputStreamReader;
 import java.net.ServerSocket;
 import java.net.Socket;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutionException;
 import java.util.concurrent.Future;
 import java.util.concurrent.FutureTask;
 import java.util.concurrent.TimeUnit;
@@ -49,7 +52,7 @@
 class Emulator {
   private static final Logger LOGGER = Logger.getLogger(Emulator.class.getName());
 
-  private final String executable;
+  private final Path executable;
   private Process process;
   private ManagedChannel channel;
   private BigtableTableAdminClient tableAdminClient;
@@ -58,47 +61,32 @@ class Emulator {
   private static final InstanceName INSTANCE_NAME =
       InstanceName.of("fake-project", "fake-instance");
 
+  // Use the gcloud installed emulator
   static Emulator createGCloud() {
-    final Process p;
+    final Path gcloudSdkPath;
 
     try {
-      p = Runtime.getRuntime().exec("gcloud info --format=value(installation.sdk_root)");
-      pipeStreamToLog(p.getErrorStream(), Level.WARNING);
-    } catch (IOException e) {
-      throw new RuntimeException("Failed to run gcloud info", e);
-    }
-
-    String sdkRoot;
-    try {
-      sdkRoot = bufferOutput(p.getInputStream()).get(1, TimeUnit.MINUTES).trim();
+      gcloudSdkPath = getGcloudSdkPath();
     } catch (Exception e) {
-      throw new RuntimeException("Failed to get gcloud sdk install path", e);
-    }
-
-    try {
-      if (p.waitFor() != 0) {
-        throw new RuntimeException("Failed to get sdk root, is gcloud sdk installed?");
-      }
-    } catch (InterruptedException e) {
-      throw new RuntimeException("Interrupted invoking gcloud", e);
+      throw new RuntimeException("Failed to get the gcloud SDK path. Is it installed?", e);
     }
 
-    String emulatorPath =
-        Paths.get(sdkRoot, "platform", "bigtable-emulator", "cbtemulator").toString();
+    Path emulatorPath =
+        gcloudSdkPath.resolve(Paths.get("platform", "bigtable-emulator", "cbtemulator"));
 
-    if (!new File(emulatorPath).exists()) {
+    if (!Files.exists(emulatorPath)) {
       throw new RuntimeException(
           "cbtemulator is not installed, please install with `gcloud components install bigtable`");
     }
 
     return new Emulator(emulatorPath);
   }
 
-  private Emulator(String executable) {
+  private Emulator(Path executable) {
     this.executable = executable;
   }
 
-  void start() throws InterruptedException, IOException, TimeoutException {
+  void start() throws Exception {
     int availablePort = getAvailablePort();
 
     process = Runtime.getRuntime().exec(executable + " -port " + "" + availablePort);
@@ -120,11 +108,14 @@ void start() throws InterruptedException, IOException, TimeoutException {
   }
 
   void stop() throws Exception {
-    dataClient.close();
-    tableAdminClient.close();
-    channel.shutdownNow();
-    channel.awaitTermination(1, TimeUnit.MINUTES);
-    process.destroy();
+    try {
+      dataClient.close();
+      tableAdminClient.close();
+      channel.shutdownNow();
+      channel.awaitTermination(1, TimeUnit.MINUTES);
+    } finally {
+      process.destroy();
+    }
   }
 
   BigtableDataClient getDataClient() {
@@ -136,6 +127,18 @@ BigtableTableAdminClient getTableAdminClient() {
   }
 
   // <editor-fold desc="Helpers">
+  private static Path getGcloudSdkPath() throws Exception {
+    Process p = Runtime.getRuntime().exec("gcloud info --format=value(installation.sdk_root)");
+    pipeStreamToLog(p.getErrorStream(), Level.WARNING);
+
+    String sdkRoot = bufferOutput(p.getInputStream()).get(1, TimeUnit.MINUTES).trim();
+
+    if (p.waitFor() != 0) {
+      throw new RuntimeException("Failed to get sdk root, is gcloud sdk installed?");
+    }
+    return Paths.get(sdkRoot);
+  }
+
   private static int getAvailablePort() {
     try (ServerSocket serverSocket = new ServerSocket(0)) {
       return serverSocket.getLocalPort();

google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/data/v2/it/env/EmulatorEnv.java

@@ -33,7 +33,7 @@ public class EmulatorEnv implements TestEnv {
   private Emulator emulator;
 
   @Override
-  public void start() throws IOException, InterruptedException, TimeoutException {
+  public void start() throws Exception {
     emulator = Emulator.createGCloud();
     emulator.start();
 

google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/data/v2/it/env/ProdEnv.java

@@ -41,10 +41,6 @@
  *   <li>{@code bigtable.instance}
  *   <li>{@code bigtable.table}
  * </ul>
- *
- * Expects the instance to exist with a table created: cbt -project igorbernstein-dev -instance
- * integration-tests createtable my-table cbt -project igorbernstein-dev -instance integration-tests
- * createfamily my-table cf
  */
 public class ProdEnv implements TestEnv {
   private static final String PROJECT_PROPERTY_NAME = "bigtable.project";

google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/data/v2/it/env/TestEnv.java

@@ -20,8 +20,13 @@
 import java.io.IOException;
 import java.util.concurrent.TimeoutException;
 
+/**
+ * Defines the interface of a target environment.
+ *
+ * <p>This allows for integration tests to run against either production or an emulator.
+ */
 public interface TestEnv {
-  void start() throws IOException, InterruptedException, TimeoutException;
+  void start() throws Exception;
 
   void stop() throws Exception;
 

google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/data/v2/it/env/TestEnvRule.java

@@ -19,6 +19,20 @@
 import java.util.logging.Logger;
 import org.junit.rules.ExternalResource;
 
+/**
+ * Simple JUnit rule to start and stop the target test environment.
+ *
+ * <p>The environment can be specified via the system property {@code bigtable.env}. The choices
+ * are:
+ *
+ * <ul>
+ *   <li>{@code emulator}: uses the cbtemulator component that can be installed by gcloud
+ *   <li>{@code prod}: uses a pre-existing production table. The target table is defined using
+ *       system properties listed in {@link ProdEnv} and application default credentials
+ * </ul>
+ *
+ * <p>By default, {@code emulator} will be used
+ */
 public class TestEnvRule extends ExternalResource {
   private static final Logger LOGGER = Logger.getLogger(TestEnvRule.class.getName());