|
| 1 | +## gcloud-java tools for testing |
| 2 | + |
| 3 | +This library provides tools to help write tests for code that uses gcloud-java services. |
| 4 | + |
| 5 | +### Testing code that uses Datastore |
| 6 | + |
| 7 | +#### On your machine |
| 8 | + |
| 9 | +You can test against a temporary local datastore by following these steps: |
| 10 | + |
| 11 | +1. Start the local datastore emulator using `LocalGcdHelper`. This can be done in two ways: |
| 12 | + - Run `LocalGcdHelper.java`'s `main` method with arguments `START` and (optionally) `--port=<port number>`. This will create a temporary folder on your computer and bind `localhost:<port number>` for communication with the local datastore. The port number is an optional argument. If no port number is specified, port 8080 will be used. |
| 13 | + - Call `LocalGcdHelper.start(<project ID>, <port number>)` before running your tests. Save the `LocalGcdHelper` object returned so that you can stop the emulator later. |
| 14 | + |
| 15 | +2. In your program, create and use a datastore whose host is set host to `localhost:<port number>`. For example, |
| 16 | + ```java |
| 17 | + DatastoreOptions options = DatastoreOptions.builder() |
| 18 | + .projectId(PROJECT_ID) |
| 19 | + .host("http://localhost:8080") |
| 20 | + .build(); |
| 21 | + Datastore localDatastore = DatastoreFactory.instance().get(options); |
| 22 | + ``` |
| 23 | +3. Run your tests. |
| 24 | + |
| 25 | +4. Stop the local datastore emulator. |
| 26 | + - If you ran `LocalGcdHelper.java`'s `main` function to start the emulator, run `LocalGcdHelper.java`'s `main` method with arguments `STOP` and (optionally) `--port=<port number>`. If the port is not supplied, the program will attempt to close the last port started. |
| 27 | + - If you ran `LocalGcdHelper.start()` to start the emulator, call the `stop()` method on the `LocalGcdHelper` object returned by `LocalGcdHelper.start()`. |
| 28 | + |
| 29 | +#### On a remote machine |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | + ```java |
| 34 | + DatastoreOptions options = DatastoreOptions.builder() |
| 35 | + .projectId(PROJECT_ID) |
| 36 | + .host("http://<hostname of machine>:<port>") |
| 37 | + .build(); |
| 38 | + Datastore localDatastore = DatastoreFactory.instance().get(options); |
| 39 | + ``` |
| 40 | + |
| 41 | +Note that the remote datastore must be running before your tests are run. |
| 42 | + |
| 43 | +### Testing code that uses Storage |
| 44 | + |
| 45 | +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: |
| 46 | + |
| 47 | +1. Create a test Google Cloud project. |
| 48 | + |
| 49 | +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]. |
| 50 | + |
| 51 | +3. Create a `RemoteGcsHelper` object using your project ID and JSON key. |
| 52 | +Here is an example that uses the `RemoteGcsHelper` to create a bucket. |
| 53 | + ```java |
| 54 | + RemoteGcsHelper gcsHelper = RemoteGcsHelper.create(PROJECT_ID, "/path/to/my/JSON/key.json"); |
| 55 | + Storage storage = StorageFactory.instance().get(gcsHelper.options()); |
| 56 | + String bucket = RemoteGcsHelper.generateBucketName(); |
| 57 | + storage.create(BucketInfo.of(bucket)); |
| 58 | + ``` |
| 59 | + |
| 60 | +4. Run your tests. |
| 61 | + |
| 62 | +5. Clean up the test project by using `forceDelete` to clear any buckets used. |
| 63 | +Here is an example that clears the bucket created in Step 3 with a timeout of 5 seconds. |
| 64 | + ```java |
| 65 | + RemoteGcsHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS); |
| 66 | + ``` |
| 67 | + |
| 68 | + |
| 69 | +[cloud-platform-storage-authentication]:https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts |
0 commit comments