diff --git a/SUPPORTING_NEW_SERVICES.md b/SUPPORTING_NEW_SERVICES.md index 7692a38a003c..b7d24be1acba 100644 --- a/SUPPORTING_NEW_SERVICES.md +++ b/SUPPORTING_NEW_SERVICES.md @@ -4,7 +4,7 @@ This document outlines how to add support for a new service in `google-cloud`. New services should be submodules located in a folder within the main repository, built using Maven. A new service should contain the following items: -* An API layer, with which users will interact. This includes model objects and a service class. +* An API layer, with which users will interact. This includes model objects and a service class. * An SPI layer, which translates google-cloud API calls into RPCs using an autogenerated client library. In almost all use cases, the user will not directly interact with this code. Separating this code from the API layer provides two benefits. First, it allows the API layer to remain stable despite changes to the autogenerated libraries used. Second, it makes testing easier, since the RPC implementation can be substituted with a mock. * A test helper class, which allows users to easily interact with a local service emulator (if possible). If there is no emulator available and the service is too complex to create a mock, then a remote test helper should be provided to separate test data from other user data and enable easy cleanup. * Tests, including unit tests and integration tests. @@ -61,9 +61,7 @@ Test helper classes should be located in the package `com.google.cloud.servicena There are three types of test helpers: * When a local emulator is already available, your test helper should launch that emulator and return service options to connect to that local emulator. This enables both users and our own library to run unit tests easily. An example of this type of helper is `LocalDatastoreHelper`. Google Cloud Datastore provides a script that launches a local datastore, so `LocalDatastoreHelper` launches that script in a separate process when the user calls `start()`. -* When there is no local emulator but the service is simple enough to write an emulator, you should do so. The emulator should listen to a port for requests, process those requests, and send responses back, being as true to the actual service as possible. Dependencies in this mock should be as lightweight as possible. Be sure to document differences between your emulator and the actual service. Examples of this type of test helper are `LocalResourceManagerHelper` and `LocalDnsHelper`. - -* When there is no local emulator and the service is too complex to write a solid emulator, the test helper should contain methods to get options and to help isolate test data from production data. `RemoteStorageHelper` is an example of this type of test helper, since there is no local emulator for Google Cloud Storage (at the time that this was written) and because the Google Cloud Storage API is complex. `RemoteStorageHelper` has methods to: +* When there is no local emulator, the test helper should contain methods to get options and to help isolate test data from production data. `RemoteStorageHelper` is an example of this type of test helper, since there is no local emulator for Google Cloud Storage (at the time that this was written) and because the Google Cloud Storage API is complex. `RemoteStorageHelper` has methods to: * Get service options settings. * Create a test bucket with a sufficiently obscure name (to separate the bucket from any of the users other data). * Clean up data left over from tests in that test bucket. diff --git a/TESTING.md b/TESTING.md index 67d8c6650cd9..a42530713e40 100644 --- a/TESTING.md +++ b/TESTING.md @@ -5,7 +5,6 @@ This library provides tools to help write tests for code that uses the following - [BigQuery] (#testing-code-that-uses-bigquery) - [Compute] (#testing-code-that-uses-compute) - [Datastore] (#testing-code-that-uses-datastore) -- [DNS] (#testing-code-that-uses-dns) - [Logging] (#testing-code-that-uses-logging) - [PubSub] (#testing-code-that-uses-pubsub) - [Resource Manager] (#testing-code-that-uses-resource-manager) @@ -113,41 +112,6 @@ We recommend that you start the emulator on the remote machine using the [Google gcloud beta emulators datastore start --host-port : ``` -### Testing code that uses DNS - -#### On your machine - -You can test against an in-memory local DNS by following these steps: - -1. Before running your testing code, start the DNS emulator `LocalDnsHelper`. This can be done as follows: - - ```java - long delay = 0; - LocalDnsHelper helper = LocalDnsHelper.create(delay); - helper.start(); - ``` - - This will spawn a server thread that listens to `localhost` at an ephemeral port for DNS requests. - The `delay` parameter determines if change requests should be processed synchronously - (value `0`) or in a separate thread with a minimum of delay of `delay` milliseconds. - -2. In your program, create the DNS service by using the helper's `getOptions()` method. -For example: - - ```java - Dns dns = LocalDnsHelper.getOptions().getService(); - ``` - -3. Run your tests. - -4. Stop the DNS emulator. - - ```java - helper.stop(); - ``` - - This method will block until the server thread has been terminated. - ### Testing code that uses Logging Currently, there isn't an emulator for Stackdriver Logging, so an alternative is to create a test @@ -251,7 +215,7 @@ Currently, there isn't an emulator for Google Cloud Storage, so an alternative i 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]. +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 `RemoteStorageHelper` object using your project ID and JSON key. Here is an example that uses the `RemoteStorageHelper` to create a bucket.