From 3751460021aeba8a2043b709773c9436340a6947 Mon Sep 17 00:00:00 2001 From: Ajay Kannan Date: Tue, 6 Oct 2015 19:40:18 -0700 Subject: [PATCH 1/5] Document how to test --- TESTING.md | 63 +++++++++++++++++++++++++++++++++ gcloud-java-datastore/README.md | 8 +++++ gcloud-java-storage/README.md | 7 ++++ 3 files changed, 78 insertions(+) create mode 100644 TESTING.md diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 000000000000..d8e8ae6689b0 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,63 @@ +## gcloud-java tools for testing + +gcloud-java provides tools to make testing your application easier. + +### Testing interactions with Datastore + +#### On your machine + +You can test against a temporary local datastore by following these steps: + +1. Start the local datastore emulator using `LocalGcdHelper`. This can be done in two ways: + - Run `LocalGcdHelper.java`'s `main` method with arguments `START` and (optionally) `--port=`. This will create a temporary folder on your computer and bind `localhost:` for communication with the local datastore. The port number is an optional argument. If no port number is specified, port 8080 will be used. + - Call `LocalGcdHelper.start(, )` before running your tests. Save the `LocalGcdHelper` object returned so that you can stop the emulator later. + +2. In your program, create and use a datastore whose host is set host to `localhost:`. For example, + ```java + DatastoreOptions options = DatastoreOptions.builder() + .projectId(PROJECT_ID) + .host("localhost:8080") + .build(); + Datastore localDatastore = DatastoreFactory.instance().get(options); + ``` +3. Run your tests. + +4. Stop the local datastore emulator. + - If you ran `LocalGcdHelper.java`'s `main` function to start the emulator, run `LocalGcdHelper.java`'s `main` method with arguments `STOP` and (optionally) `--port=`. If the port is not supplied, the program will attempt to close the last port started. + - If you ran `LocalGcdHelper.start()` to start the emulator, call the `stop()` method on the `LocalGcdHelper` object returned by `LocalGcdHelper.start()`. + +#### On a remote machine + +You can test against a remote datastore emulator as well. To do this, set the `DatastoreOptions` project endpoint to the hostname of the remote machine, like the example below. + + ```java + DatastoreOptions options = DatastoreOptions.builder() + .projectId(PROJECT_ID) + .host("http://") + .build(); + Datastore localDatastore = DatastoreFactory.instance().get(options); + ``` + +Note that the remote datastore must be running before your tests are run. Also note that the `host` argument must start with "http://" or "https://". + + +### Testing interactions with Storage + +There currently isn't an emulator for Google Cloud Storage, so an alternative is to create a test project. `RemoteGcsHelper` 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 App Engine project. + +2. Create and download a JSON key by going to the Google Developer's Console and clicking API's & Auth > Credentials > Add Credentials > Service Credentials. Choose "JSON", download the file, and note its location. + +3. Set environment variables `GCLOUD_TESTS_PROJECT_ID` and `GCLOUD_TESTS_KEY_PATH` according to your test project's ID and the location of the newly-downloaded JSON key file. + +4. Create and and use a `RemoteGcsHelper` object. +Here is an example that uses the RemoteGcsHelper to create a bucket and clear the bucket at the end of the test. +```java +RemoteGcsHelper gcsHelper = RemoteGcsHelper.create(); +Storage storage = StorageFactory.instance().get(gcsHelper.options()); +String bucket = RemoteGcsHelper.generateBucketName(); +storage.create(BucketInfo.of(bucket)); +// Do tests using Storage +RemoteGcsHelper.deleteBucketRecursively(storage, bucket, 5, TimeUnit.SECONDS); +``` diff --git a/gcloud-java-datastore/README.md b/gcloud-java-datastore/README.md index 3ea30c871124..ba3d4f00af42 100644 --- a/gcloud-java-datastore/README.md +++ b/gcloud-java-datastore/README.md @@ -69,6 +69,13 @@ if (entity == null) { } ``` +Testing +------- + +This library makes testing interactions with Cloud Datastore easier by using a local datastore emulator. + +See [TESTING] to read more about testing locally. + Contributing ------------ @@ -98,6 +105,7 @@ Apache 2.0 - See [LICENSE] for more information. [CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md [LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE +[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md [cloud-platform]: https://cloud.google.com/ [cloud-datastore]: https://cloud.google.com/datastore/docs [cloud-datastore-docs]: https://cloud.google.com/datastore/docs diff --git a/gcloud-java-storage/README.md b/gcloud-java-storage/README.md index c1ee260a076e..e462d7fd67ef 100644 --- a/gcloud-java-storage/README.md +++ b/gcloud-java-storage/README.md @@ -26,6 +26,12 @@ Add this to your pom.xml file ``` +Testing +------- + +This library makes testing interactions with Cloud Storage more convenient. + +See [TESTING] to read more about testing. Contributing ------------ @@ -56,6 +62,7 @@ Apache 2.0 - See [LICENSE] for more information. [CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md [LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE +[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md [cloud-platform]: https://cloud.google.com/ [cloud-storage]: https://cloud.google.com/storage/ From 25bde6027f987b68eae07b1be4b02a604d5f4a97 Mon Sep 17 00:00:00 2001 From: Ajay Kannan Date: Wed, 7 Oct 2015 09:21:58 -0700 Subject: [PATCH 2/5] Testing doc fixes and adding/updating examples --- TESTING.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/TESTING.md b/TESTING.md index d8e8ae6689b0..9fdb65bf4537 100644 --- a/TESTING.md +++ b/TESTING.md @@ -38,26 +38,32 @@ You can test against a remote datastore emulator as well. To do this, set the ` Datastore localDatastore = DatastoreFactory.instance().get(options); ``` -Note that the remote datastore must be running before your tests are run. Also note that the `host` argument must start with "http://" or "https://". +Note that the remote datastore must be running before your tests are run. Also note that the `host` argument must start with "http://" or "https://" if you are testing with a remote machine. ### Testing interactions with Storage There currently isn't an emulator for Google Cloud Storage, so an alternative is to create a test project. `RemoteGcsHelper` 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 App Engine project. +1. Create a test Google Cloud project. -2. Create and download a JSON key by going to the Google Developer's Console and clicking API's & Auth > Credentials > Add Credentials > Service Credentials. Choose "JSON", download the file, and note its location. +2. Create and 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. Set environment variables `GCLOUD_TESTS_PROJECT_ID` and `GCLOUD_TESTS_KEY_PATH` according to your test project's ID and the location of the newly-downloaded JSON key file. +3. Set environment variables `GCLOUD_TESTS_PROJECT_ID` and `GCLOUD_TESTS_KEY` according to your test project's ID and the location of the newly-downloaded JSON key file. On linux and mac, for example, + ``` + export GCLOUD_TESTS_PROJECT_ID= + export GCLOUD_TESTS_KEY=/path/to/JSON/key.json + ``` 4. Create and and use a `RemoteGcsHelper` object. -Here is an example that uses the RemoteGcsHelper to create a bucket and clear the bucket at the end of the test. +Here is an example that uses the `RemoteGcsHelper` to create a bucket and clear the bucket at the end of the test. ```java RemoteGcsHelper gcsHelper = RemoteGcsHelper.create(); Storage storage = StorageFactory.instance().get(gcsHelper.options()); String bucket = RemoteGcsHelper.generateBucketName(); storage.create(BucketInfo.of(bucket)); // Do tests using Storage -RemoteGcsHelper.deleteBucketRecursively(storage, bucket, 5, TimeUnit.SECONDS); +RemoteGcsHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS); ``` + +[cloud-platform-storage-authentication]:https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts From 59722faff73c678d55e85184e40408c6a4e4ef9e Mon Sep 17 00:00:00 2001 From: Ajay Kannan Date: Wed, 7 Oct 2015 21:31:32 -0700 Subject: [PATCH 3/5] Minor wording and link changes to testing readme. --- README.md | 53 ++++++++++++++++++++++++++++++++- TESTING.md | 40 +++++++++++-------------- gcloud-java-datastore/README.md | 6 ++-- gcloud-java-storage/README.md | 4 +-- 4 files changed, 74 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 82d133495559..90a429149f6c 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Java idiomatic client for [Google Cloud Platform][cloud-platform] services. This client supports the following Google Cloud Platform services: - [Google Cloud Datastore] (#google-cloud-datastore) +- [Google Cloud Storage] (#google-cloud-storage)