diff --git a/TESTING.md b/TESTING.md index 1ee7b2f98164..e446f492dc87 100644 --- a/TESTING.md +++ b/TESTING.md @@ -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 @@ -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(":") + .authCredentials(AuthCredentials.noAuth()) + .build(); + PubSub localPubsub= options.service(); ``` ### Testing code that uses Resource Manager @@ -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(":") - .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 diff --git a/gcloud-java-pubsub/README.md b/gcloud-java-pubsub/README.md index aa8bd5c5ad5c..e4e5e8822dab 100644 --- a/gcloud-java-pubsub/README.md +++ b/gcloud-java-pubsub/README.md @@ -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) @@ -24,7 +24,7 @@ Standard. `gcloud-java-pubsub` will work on App Engine Flexible. Add this to your pom.xml file ```xml - com.google.gcloud + com.google.cloud gcloud-java-pubsub 0.2.4