u[date readme.md

docs/README.md

@@ -41,6 +41,7 @@ Also see the [FAQ](./faq.md).
 1. [Integration Tests](../test/integration/connect/envoy/README.md)
 1. [Upgrade Tests](../test/integration/consul-container/test/upgrade/README.md)
 1. [Remote Debugging Integration Tests](../test/integration/consul-container/test/debugging.md)
+1. [Peering Common Topology Tests](../test-integ/peering_commontopo/README.md)
 
 ## Important Directories
 

test-integ/peering_commontopo/README.md

@@ -1,12 +1,66 @@
-# peering_commontopo
+# CONSUL PEERING COMMON TOPOLOGY TESTS
 
 These peering tests all use a `commonTopo` (read: "common topology") to enable sharing a deployment of a Consul. Sharing a deployment of Consul cuts down on setup time.
 
-This is only possible if two constraints are followed:
+To run these tests, you will need to have docker installed. Next, make sure that you have all the required consul containers built:
 
+```
+make test-compat-integ-setup
+```
+
+## Non-Shared CommonTopo Tests
+
+The tests in question are designed in a manner that modifies the topology. As a result, it is not possible to share the testing environment across these tests.
+
+## Shared CommonTopo Tests
+
+The tests in question are designed in a manner that does not modify the topology in any way that would interfere with other tests. As a result, it is possible to share the testing environment across these tests.
+
+To run all consul peering tests with no shared topology, run the following command:
+
+```
+cd /path/to/peering_commontopo
+go test -timeout=10m -v -no-share-topo . 
+```
+
+To run all peering tests with shared topology only:
+
+```
+cd /path/to/peering_commontopo
+go test -timeout=10m -run '^TestSuitesOnSharedTopo' -v . 
+```
+
+To run individual peering topology tests:
+
+```
+cd /path/to/peering_commontopo
+go test -timeout=10m -run '^TestSuiteExample' -v -no-share-topo .    
+```
+
+## Local Development and Testing
+
+If writing tests for peering with no shared topology, this recommendation does not apply. The following methods below not necessarily need to be implmented. For shared topology tests, all the methods in the `sharedTopoSuite` interface must be implemented.
+
+- `testName()` prepends the test suite name to each test in the test suite.
 - `setup()` phase must ensure that any resources added to the topology cannot interfere with other tests. Principally by prefixing.
 - `test()` phase must be "passive" and not mutate the topology in any way that would interfere with other tests.
 
-Some of these tests *do* mutate in their `test()` phase, and while they use `commonTopo` for the purpose of code sharing, they are not included in the "shared topo" tests in `all_sharedtopo_test.go`.
+Common topology peering tests are defined in the [test-integ/peering_commontopo/](/test-integ/peering_commontopo/) directory and new peering integration tests should always be added to this location. Adding integration tests that does not modify the topology should always start by invoking
+
+```go
+runShareableSuites(t, testSuiteExample)
+```
+
+else
+
+```go
+func TestSuiteExample(t *testing.T) {
+ ct := NewCommonTopo(t)
+ s := &testSuiteExample{}
+ s.setup(t, ct)
+ ct.Launch(t)
+ s.test(t, ct)
+}
+```
 
-Tests that are "shared topo" can also be run in an independent manner, gated behind the `-no-reuse-common-topo` flag. The same flag also prevents the shared topo suite from running. So `go test .` (without the flag) runs all shared topo-capable tests in *shared topo mode*, as well as shared topo-incapable tests; and `go test -no-reuse-common-topo` runs all shared topo-capable tests *individidually*, as well as the shared topo-incapable tests. Mostly this is so that when working on a single test, you don't also need to run other tests, but by default when running `go test .` the usual way, you run all tests in the fastest way.
+Some of these tests *do* mutate in their `test()` phase, and while they use `commonTopo` for the purpose of code sharing, they are not included in the "shared topo" tests in `sharedtopology_test.go`.