Skip to content

Commit

Permalink
Add missing links to TESTING.md, fix ordering, add Compute section
Browse files Browse the repository at this point in the history
  • Loading branch information
@mziccard
mziccard committed Jun 30, 2016
1 parent 68e61d1 commit b7f8480
Showing 1 changed file with 103 additions and 74 deletions.
177 changes: 103 additions & 74 deletions TESTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,68 @@

This library provides tools to help write tests for code that uses the following gcloud-java services:

- [BigQuery] (#testing-code-that-uses-bigquery)
- [Compute] (#testing-code-that-uses-compute)
- [Datastore] (#testing-code-that-uses-datastore)
- [Storage] (#testing-code-that-uses-storage)
- [DNS] (#testing-code-that-uses-dns)
- [PubSub] (#testing-code-that-uses-pubsub)
- [Resource Manager] (#testing-code-that-uses-resource-manager)
- [BigQuery] (#testing-code-that-uses-bigquery)
- [Storage] (#testing-code-that-uses-storage)

### Testing code that uses BigQuery

Currently, there isn't an emulator for Google BigQuery, so an alternative is to create a test
project. `RemoteBigQueryHelper` contains convenience methods to make setting up and cleaning up the
test project easier. To use this class, follow the steps below:

1. Create a test Google Cloud project.

2. Download a [JSON service account credentials file][create-service-account] from the Google
Developer's Console.

3. Create a `RemoteBigQueryHelper` object using your project ID and JSON key.
Here is an example that uses the `RemoteBigQueryHelper` to create a dataset.
```java
RemoteBigQueryHelper bigqueryHelper =
RemoteBigQueryHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json"));
BigQuery bigquery = bigqueryHelper.options().service();
String dataset = RemoteBigQueryHelper.generateDatasetName();
bigquery.create(DatasetInfo.builder(dataset).build());
```

4. Run your tests.

5. Clean up the test project by using `forceDelete` to clear any datasets used.
Here is an example that clears the dataset created in Step 3.
```java
RemoteBigQueryHelper.forceDelete(bigquery, dataset);
```

### Testing code that uses Compute

Currently, there isn't an emulator for Google Compute, so an alternative is to create a test
project. `RemoteComputeHelper` contains convenience methods to make setting up the test project
easier. To use this class, follow the steps below:

1. Create a test Google Cloud project.

2. Download a [JSON service account credentials file][create-service-account] from the Google
Developer's Console.

3. Create a `RemoteComputeHelper` object using your project ID and JSON key. Here is an example that
uses the `RemoteComputeHelper` to create an address.
```java
RemoteComputeHelper computeHelper =
RemoteBigQueryHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json"));
Compute compute = computeHelper.options().service();
// Pick a name for the resource with low probability of clashing
String addressName = RemoteComputeHelper.baseResourceName() + "address";
AddressId addressId = RegionAddressId.of(REGION, addressName);
AddressInfo addressInfo = AddressInfo.of(addressId);
Operation operation = compute.create(addressInfo);
```

4. Run your tests.

### Testing code that uses Datastore

Expand Down Expand Up @@ -88,30 +146,45 @@ You can test against an in-memory local DNS by following these steps:

This method will block until the server thread has been terminated.

### Testing code that uses Storage
### Testing code that uses Pub/Sub

Currently, there isn't an emulator for Google Cloud Storage, so an alternative is to create a test project. `RemoteStorageHelper` contains convenience methods to make setting up and cleaning up the test project easier. To use this class, follow the steps below:
#### On your machine

1. Create a test Google Cloud project.
You can test against a temporary local Pub/Sub by following these steps:

2. Download a JSON service account credentials file from the Google Developer's Console. See more about this on the [Google Cloud Platform Storage Authentication page][cloud-platform-storage-authentication].
1. Start the local Pub/Sub emulator before running your tests using `LocalPubSubHelper`'s `create`
and `start` methods. This will bind a port for communication with the local Pub/Sub emulator.
```java
LocalPubSubHelper helper = LocalPubSubHelper.create();

3. Create a `RemoteStorageHelper` object using your project ID and JSON key.
Here is an example that uses the `RemoteStorageHelper` to create a bucket.
helper.start(); // Starts the local Pub/Sub emulator in a separate process
```

2. Create and use a `PubSub` object with the options given by the `LocalPubSubHelper` instance. For
example:
```java
RemoteStorageHelper helper =
RemoteStorageHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json"));
Storage storage = helper.options().service();
String bucket = RemoteStorageHelper.generateBucketName();
storage.create(BucketInfo.of(bucket));
PubSub localPubsub = helper.options().service();
```

4. Run your tests.
3. Run your tests.

5. Clean up the test project by using `forceDelete` to clear any buckets used.
Here is an example that clears the bucket created in Step 3 with a timeout of 5 seconds.
4. Stop the local Pub/Sub emulator by calling the `stop()` method, like so:
```java
RemoteStorageHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
helper.stop();
```

#### On a remote machine

You can test against a remote Pub/Sub emulator as well. To do this, set the `PubSubOptions` project
endpoint to the hostname of the remote machine, like the example below.

```java
PubSubOptions options = PubSubOptions.builder()
.projectId("my-project-id") // must match project ID specified on remote machine
.host("<hostname of machine>:<port>")
.authCredentials(AuthCredentials.noAuth())
.build();
PubSub localPubsub= options.service();
```

### Testing code that uses Resource Manager
Expand Down Expand Up @@ -145,74 +218,30 @@ You can test against an in-memory local Resource Manager by following these step

This method will block until the server thread has been terminated.

### Testing code that uses BigQuery
### Testing code that uses Storage

Currently, there isn't an emulator for Google BigQuery, so an alternative is to create a test
project. `RemoteBigQueryHelper` contains convenience methods to make setting up and cleaning up the
test project easier. To use this class, follow the steps below:
Currently, there isn't an emulator for Google Cloud Storage, so an alternative is to create a test project. `RemoteStorageHelper` contains convenience methods to make setting up and cleaning up the test project easier. To use this class, follow the steps below:

1. Create a test Google Cloud project.

2. Download a [JSON service account credentials file][create-service-account] from the Google
Developer's Console.
2. Download a JSON service account credentials file from the Google Developer's Console. See more about this on the [Google Cloud Platform Storage Authentication page][cloud-platform-storage-authentication].

3. Create a `RemoteBigQueryHelper` object using your project ID and JSON key.
Here is an example that uses the `RemoteBigQueryHelper` to create a dataset.
3. Create a `RemoteStorageHelper` object using your project ID and JSON key.
Here is an example that uses the `RemoteStorageHelper` to create a bucket.
```java
RemoteBigQueryHelper bigqueryHelper =
RemoteBigQueryHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json"));
BigQuery bigquery = bigqueryHelper.options().service();
String dataset = RemoteBigQueryHelper.generateDatasetName();
bigquery.create(DatasetInfo.builder(dataset).build());
RemoteStorageHelper helper =
RemoteStorageHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json"));
Storage storage = helper.options().service();
String bucket = RemoteStorageHelper.generateBucketName();
storage.create(BucketInfo.of(bucket));
```

4. Run your tests.

5. Clean up the test project by using `forceDelete` to clear any datasets used.
Here is an example that clears the dataset created in Step 3.
```java
RemoteBigQueryHelper.forceDelete(bigquery, dataset);
```

### Testing code that uses Pub/Sub

#### On your machine

You can test against a temporary local Pub/Sub by following these steps:

1. Start the local Pub/Sub emulator before running your tests using `LocalPubSubHelper`'s `create`
and `start` methods. This will bind a port for communication with the local Pub/Sub emulator.
```java
LocalPubSubHelper helper = LocalPubSubHelper.create();

helper.start(); // Starts the local Pub/Sub emulator in a separate process
```

2. Create and use a `PubSub` object with the options given by the `LocalPubSubHelper` instance. For
example:
```java
PubSub localPubsub = helper.options().service();
```

3. Run your tests.

4. Stop the local Pub/Sub emulator by calling the `stop()` method, like so:
```java
helper.stop();
```

#### On a remote machine

You can test against a remote Pub/Sub emulator as well. To do this, set the `PubSubOptions` project
endpoint to the hostname of the remote machine, like the example below.

5. Clean up the test project by using `forceDelete` to clear any buckets used.
Here is an example that clears the bucket created in Step 3 with a timeout of 5 seconds.
```java
PubSubOptions options = PubSubOptions.builder()
.projectId("my-project-id") // must match project ID specified on remote machine
.host("<hostname of machine>:<port>")
.authCredentials(AuthCredentials.noAuth())
.build();
PubSub localPubsub= options.service();
RemoteStorageHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
```

[cloud-platform-storage-authentication]:https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts
Expand Down

0 comments on commit b7f8480

Please sign in to comment.