Make obtaining the Testable interface actually part of the interface.

doc.go

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Package gae provides a fakable wrapped interface for the appengine SDK's
 // APIs. This means that it's possible to mock all of the supported appengine
 // APIs for testing (or potentially implement a different backend for them).
 //
 // Features
 //
@@ skipping 90 matching lines @@
 //    service.Interface    - the main user-friendly service interface.
 //
 //    service.RawInterface - the internal service interface used by service
 //                           and filter implementations. Note that some services
 //                           like Info don't distinguish between the service
 //                           interface and the user interface. This interface is
 //                           typically a bit lower level than Interface and
 //                           lacks convenience methods.
 //
 //    service.Testable     - any additional methods that a 'testing'
-//                           implementation should provide. It's expected that
-//                           tests will cast the RawInterface from GetRaw() to
-//                           Testable in order to access these methods.
+//                           implementation should provide. This can be accessed
+//                           via the Testable method on Interface or
+//                           RawInterface. If the current implementation is not
+//                           testable, it will return nil. This is only meant to
+//                           be accessed when testing.
 //
 //    service.RawFactory   - a function returning a RawInterface
 //
 //    service.RawFilter    - a function returning a new RawInterface based on
 //                           the previous filtered interface. Filters chain
 //                           together to allow behavioral service features
 //                           without needing to agument the underlying service
 //                           implementations directly.
 //
 // And common functions are:
@@ skipping 91 matching lines @@
 // and the state can be observed to see how many times each API was invoked.
 // Since filters stack, we can compare counts from rawCount versus userCount to
 // see how many calls to the actual real datastore went through, vs. how many
 // went to memcache, for example.
 //
 // Note that Filters apply only to the service.RawInterface. All implementations
 // of service.Interface boil down to calls to service.RawInterface methods, but
 // it's possible that bad calls to the service.Interface methods could return
 // an error before ever reaching the filters or service implementation.
 package gae