diff --git a/README.md b/README.md index baca66b35ec1..9836691e8563 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,13 @@ if (!blob.exists()) { } ``` +Testing +------- + +This library provides tools to help write tests for code that uses gcloud-java services. + +See [TESTING] to read more about using our testing helpers. + Contributing ------------ @@ -159,6 +166,7 @@ Apache 2.0 - See [LICENSE] for more information. [CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md [code-of-conduct]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CODE_OF_CONDUCT.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/TESTING.md b/TESTING.md new file mode 100644 index 000000000000..158d71be2e91 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,69 @@ +## gcloud-java tools for testing + +This library provides tools to help write tests for code that uses gcloud-java services. + +### Testing code that uses 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("http://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. + +### Testing code that uses Storage + +Currently, there 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 Cloud project. + +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 `RemoteGcsHelper` object using your project ID and JSON key. +Here is an example that uses the `RemoteGcsHelper` to create a bucket. + ```java + RemoteGcsHelper gcsHelper = RemoteGcsHelper.create(PROJECT_ID, "/path/to/my/JSON/key.json"); + Storage storage = StorageFactory.instance().get(gcsHelper.options()); + String bucket = RemoteGcsHelper.generateBucketName(); + storage.create(BucketInfo.of(bucket)); + ``` + +4. 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. + ```java + RemoteGcsHelper.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-datastore/README.md b/gcloud-java-datastore/README.md index 3ea30c871124..9a5de1ec9890 100644 --- a/gcloud-java-datastore/README.md +++ b/gcloud-java-datastore/README.md @@ -69,6 +69,13 @@ if (entity == null) { } ``` +Testing +------- + +This library has tools to help write tests for code that uses the Datastore. + +See [TESTING] to read more about testing. + 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#testing-code-that-uses-datastore [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..776bcb3db84a 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 has tools to help make tests for code using Cloud Storage. + +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#testing-code-that-uses-storage [cloud-platform]: https://cloud.google.com/ [cloud-storage]: https://cloud.google.com/storage/