spectator-go testing advice (#178)

docs/spectator/lang/go/migrations.md

@@ -1,6 +1,6 @@
 ## Migrating from 0.X to 2.X
 
-Version 0.3 consists of a major rewrite that turns spectator-go into a thin client designed to send metrics through
+Version 2.X consists of a major rewrite that turns spectator-go into a thin client designed to send metrics through
 [spectatord](https://github.com/Netflix-Skunkworks/spectatord). As a result some functionality has been moved to other
 packages or removed.
 
@@ -9,9 +9,10 @@ packages or removed.
 #### Writers
 
 `spectator.Registry` now supports different writers. The default writer is `writer.UdpWriter` which sends metrics
-to spectatord through UDP.
+to [spectatord](https://github.com/Netflix-Skunkworks/spectatord) through UDP.
 
 Writers can be configured through `spectator.Config.Location`.
+
 Possible values are:
 
 - `none`: Configures a no-op writer that does nothing. Can be used to disable metrics collection.
@@ -22,8 +23,8 @@ Possible values are:
 - `unix:///path/to/socket`: Writes metrics to a Unix domain socket.
 - `udp://host:port`: Writes metrics to a UDP socket.
 
-Location can also be set through the environment variable `SPECTATOR_OUTPUT_LOCATION`. If both are set, the environment variable
-takes precedence over the passed config. 
+Location can also be set through the environment variable `SPECTATOR_OUTPUT_LOCATION`. If both are set, the environment
+variable takes precedence over the passed config. 
 
 The environment variable `SPECTATOR_OUTPUT_LOCATION` can be set to `none` to disable metrics collection.
 
@@ -56,8 +57,7 @@ Note that common tags sourced by [spectatord](https://github.com/Netflix-Skunkwo
 
 - Runtime metrics collection has been moved
   to [spectator-go-runtime-metrics](https://github.com/Netflix/spectator-go-runtime-metrics). Follow instructions in
-  the [README](https://github.com/Netflix/spectator-go-runtime-metrics) to enable
-  collection.
+  the [README](https://github.com/Netflix/spectator-go-runtime-metrics) to enable collection.
 - Some types have been moved to different packages. For example, `spectator.Counter` is now in `meter.Counter`.
 
 ### Removed
@@ -67,7 +67,8 @@ Note that common tags sourced by [spectatord](https://github.com/Netflix-Skunkwo
   measurements.
 - `spectator.Clock` has been removed. Use the standard `time` package instead.
 - `spectator.Config` has been greatly simplified.
-- `spectator.Registry` no longer has a `Start()` function. It is now automatically started when created.
+- `spectator.Registry` no longer has a `Start()` function. The `Registry` is now effectively stateless and there is
+  nothing to start other than opening the output location.
 - `spectator.Registry` no longer has a `Stop()` function. Instead, use `Close()` to close the registry. Once the
   registry is closed, it can't be started again.
 - `spectator.Config.IpcTimerRecord` has been removed. Use a `meter.Timer` instead to record Ipc metrics.
@@ -82,16 +83,55 @@ Note that common tags sourced by [spectatord](https://github.com/Netflix-Skunkwo
   `spectator.Config` before creating the Registry.
 - File-based configuration is no longer supported.
 
-### Migration steps
+### Migration Steps
 
 1. Make sure you're not relying on any of the [removed functionality](#removed).
 2. Update imports to use `meters` package instead of `spectator` for Meters.
 3. If you want to collect runtime metrics
    pull [spectator-go-runtime-metrics](https://github.com/Netflix/spectator-go-runtime-metrics) and follow the
-   instructions in the
-   [README](https://github.com/Netflix/spectator-go-runtime-metrics)
-4. If you use `PercentileDistributionSummary` or `PercentileTimer` you need to update your code to use the respective
-   functions provided by the Registry to initialize these meters.
+   instructions in the [README](https://github.com/Netflix/spectator-go-runtime-metrics).
+4. If you use `PercentileDistributionSummary` or `PercentileTimer`, then  you need to update your code to use the
+   respective functions provided by the `Registry` to initialize these meters.
 5. Remove dependency on Spectator Go Internal configuration library. Such dependency is no longer required.
-6. There is no longer an option to start or stop the registry at runtime. If you need to configure a registry that
-   doesn't emit metrics, you can use the `spectator.Config.Location` option with `none` to configure a no-op writer.
+6. There is no longer an option to start or stop the registry at runtime. If you need to configure a `Registry` that
+   doesn't emit metrics, for testing purposes, you can use the `spectator.Config.Location` option with `none` to
+   configure a no-op writer.
+
+### Writing Tests
+
+To write tests against this library, instantiate a test instance of the `Registry` and configure it to use the
+[MemoryWriter](https://github.com/Netflix/spectator-go/blob/main/spectator/writer/writer.go#L18-L21), which stores
+all updates in an `Array`. Maintain a handle to the `MemoryWriter`, then inspect the `Lines()` to verify your metrics
+updates. See the source code for more testing examples.
+
+```golang
+package app
+
+import (
+	"fmt"
+	"github.com/Netflix/spectator-go/v2/spectator/logger"
+	"github.com/Netflix/spectator-go/v2/spectator/writer"
+	"testing"
+	"time"
+)
+
+func TestRegistryWithMemoryWriter_Counter(t *testing.T) {
+	mw := &writer.MemoryWriter{}
+	r := NewTestRegistry(mw)
+
+	counter := r.Counter("test_counter", nil)
+	counter.Increment()
+	expected := "c:test_counter:1"
+	if len(mw.Lines()) != 1 || mw.Lines()[0] != expected {
+		t.Errorf("Expected '%s', got '%s'", expected, mw.Lines()[0])
+	}
+}
+
+func NewTestRegistry(mw *writer.MemoryWriter) Registry {
+	return &spectatordRegistry{
+		config: &Config{},
+		writer: mw,
+		logger: logger.NewDefaultLogger(),
+	}
+}
+```

docs/spectator/lang/py/usage.md

@@ -205,3 +205,5 @@ class ProtocolParserTest(unittest.TestCase):
         self.assertEqual({"foo": "bar", "baz": "quux"}, meter_id.tags())
         self.assertEqual("1", value)
 ```
+
+[SpectatorD]: ../../agent/usage.md