Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix pubsub's README links and TESTING.md #1092

Merged
merged 2 commits into from
Jul 1, 2016
Merged

Fix pubsub's README links and TESTING.md #1092

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
68e61d1
Rename com.google.gcloud to com.google.cloud in pubsub README
mziccard Jun 30, 2016
b7f8480
Add missing links to TESTING.md, fix ordering, add Compute section
mziccard Jun 30, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 103 additions & 74 deletions TESTING.md
View file
Open in desktop
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
4 changes: 2 additions & 2 deletions gcloud-java-pubsub/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Java idiomatic client for [Google Cloud Pub/Sub] (https://cloud.google.com/pubsu

[![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
[![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
[![Maven](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-pubsub.svg)]( https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-pubsub.svg)
[![Maven](https://img.shields.io/maven-central/v/com.google.cloud/gcloud-java-pubsub.svg)]( https://img.shields.io/maven-central/v/com.google.cloud/gcloud-java-pubsub.svg)
[![Codacy Badge](https://api.codacy.com/project/badge/grade/9da006ad7c3a4fe1abd142e77c003917)](https://www.codacy.com/app/mziccard/gcloud-java)
[![Dependency Status](https://www.versioneye.com/user/projects/56bd8ee72a29ed002d2b0969/badge.svg?style=flat)](https://www.versioneye.com/user/projects/56bd8ee72a29ed002d2b0969)

Expand All @@ -24,7 +24,7 @@ Standard. `gcloud-java-pubsub` will work on App Engine Flexible.
Add this to your pom.xml file
```xml
<dependency>
<groupId>com.google.gcloud</groupId>
<groupId>com.google.cloud</groupId>
<artifactId>gcloud-java-pubsub</artifactId>
<version>0.2.4</version>
</dependency>
Expand Down