go/packages/packagestest: add package use example

The purpose and value of packagestest is easy to understand. However,
the current API may not be easy to get started with. It includes
identifiers such as Exporter, Exported, Export, whose names may not
make it very clear in what order they are to be used, and whether
the Exporter interfaces needs to be implemented by the caller.

There are fairly common patterns of usage spread out across various
packages that use packagestest. Add an example of basic usage to the
documentation of this package that connects all of the pieces together,
so that users don't have to look for it elsewhere.

I would've preferred to add the example as example code¹, but it
doesn't seem viable to write example code for test helper packages.
There isn't a way to get a functional *testing.T in a func Example.

¹ https://golang.org/pkg/testing/#hdr-Examples

Updates golang/go#33655

Change-Id: I0b15ff7974be25a71dfd4b68f470441ce7331d18
Reviewed-on: https://go-review.googlesource.com/c/tools/+/196980
Reviewed-by: Michael Matloob <[email protected]>

Author: dmitshur

go/packages/packagestest/export.go

@@ -8,6 +8,59 @@ Package packagestest creates temporary projects on disk for testing go tools on.
 By changing the exporter used, you can create projects for multiple build
 systems from the same description, and run the same tests on them in many
 cases.
+
+Example
+
+As an example of packagestest use, consider the following test that runs
+the 'go list' command on the specified modules:
+
+	// TestGoList exercises the 'go list' command in module mode and in GOPATH mode.
+	func TestGoList(t *testing.T) { packagestest.TestAll(t, testGoList) }
+	func testGoList(t *testing.T, x packagestest.Exporter) {
+		e := packagestest.Export(t, x, []packagestest.Module{
+			{
+				Name: "gopher.example/repoa",
+				Files: map[string]interface{}{
+					"a/a.go": "package a",
+				},
+			},
+			{
+				Name: "gopher.example/repob",
+				Files: map[string]interface{}{
+					"b/b.go": "package b",
+				},
+			},
+		})
+		defer e.Cleanup()
+
+		cmd := exec.Command("go", "list", "gopher.example/...")
+		cmd.Dir = e.Config.Dir
+		cmd.Env = e.Config.Env
+		out, err := cmd.Output()
+		if err != nil {
+			t.Fatal(err)
+		}
+		t.Logf("'go list gopher.example/...' with %s mode layout:\n%s", x.Name(), out)
+	}
+
+TestGoList uses TestAll to exercise the 'go list' command with all
+exporters known to packagestest. Currently, packagestest includes
+exporters that produce module mode layouts and GOPATH mode layouts.
+Running the test with verbose output will print:
+
+	=== RUN   TestGoList
+	=== RUN   TestGoList/GOPATH
+	=== RUN   TestGoList/Modules
+	--- PASS: TestGoList (0.21s)
+	    --- PASS: TestGoList/GOPATH (0.03s)
+	        main_test.go:36: 'go list gopher.example/...' with GOPATH mode layout:
+	            gopher.example/repoa/a
+	            gopher.example/repob/b
+	    --- PASS: TestGoList/Modules (0.18s)
+	        main_test.go:36: 'go list gopher.example/...' with Modules mode layout:
+	            gopher.example/repoa/a
+	            gopher.example/repob/b
+
 */
 package packagestest