Adds 'outline' command to print the outline of specs/containers in a …

…file (#754)

* Adds 'outline' command to print the outline of specs/containers in a file

Implements feature request in #753

* outline: Add support for nodot and alias import of the ginkgo package

* outline: During a post-order traversal of an AST Node, do not derive its ginkgo metadata

The post-order traversal needs to check whether the AST Node is a ginkgo node.
That can be done by comparing the positions of the AST Node and the last
visited ginkgo node. Deriving the ginkgo metadata is not necessary.

* outline: Add backpropagation of unfocus, propagation of inherited focus/pending properties

* outline: Add instructions and script for creating/updating sample test results

To make it easier to maintain the outline tests.

* outline: Use script to re-create result samples for all tests

The content has not changed; only the JSON formatting and the filenames have
changed.

* outline: Factor the back/propagation code to helper functions

The top-level function needed to be shorter.

* outline: Refactor deriving ginkgo identifier from call expression

Again, the top-level function needed to be shorter.

* outline: Move the exported outline code into its own file

Keep the unexprted ginkgoNode code in a separate file.

* outline: Instead of aliasing ginkgoNode with outline, embed ginkgoNode in outline

An advantage of embedding is that it does not require casting. The outline
receivers does not change.

* outline: (fix) Derive the "text" of the By ginkgo call

The "text" was being ignored by mistake.

* outline: Test an outline of a "suite_test.go" file

The test and its result samples were already present, but the test was not run.

* outline: Add "indent" format

This is really just for fun. Here's an example:

``shell
ginkgo outline -format=indent outline/_testdata/normal_test.go
```

```shell
Name,Text,Start,End,Spec,Focused,Pending
Describe,NormalFixture,116,605,false,false,false
    Describe,normal,152,244,false,false,false
        It,normal,182,240,true,false,false
            By,step 1,207,219,false,false,false
            By,step 2,223,235,false,false,false
    Context,normal,247,307,false,false,false
        It,normal,276,303,true,false,false
    When,normal,310,367,false,false,false
        It,normal,336,363,true,false,false
    It,normal,370,396,true,false,false
    Specify,normal,399,430,true,false,false
    Measure,normal,433,480,true,false,false
```

It also happens to look nice piped through `column`:

```shell
ginkgo outline -format=indent outline/_testdata/normal_test.go | column --table -s=","
```

```
Name            Text           Start  End  Spec   Focused  Pending
Describe        NormalFixture  116    605  false  false    false
    Describe    normal         152    244  false  false    false
        It      normal         182    240  true   false    false
            By  step 1         207    219  false  false    false
            By  step 2         223    235  false  false    false
    Context     normal         247    307  false  false    false
        It      normal         276    303  true   false    false
    When        normal         310    367  false  false    false
        It      normal         336    363  true   false    false
    It          normal         370    396  true   false    false
    Specify     normal         399    430  true   false    false
    Measure     normal         433    480  true   false    false
```

ginkgo/main.go

@@ -111,6 +111,11 @@ will output an executable file named `package.test`.  This can be run directly o
 
 	ginkgo <path-to-package.test>
 
+
+To print an outline of Ginkgo specs and containers in a file:
+
+	gingko outline <filename>
+
 To print out Ginkgo's version:
 
 	ginkgo version
@@ -172,6 +177,7 @@ func init() {
 	Commands = append(Commands, BuildUnfocusCommand())
 	Commands = append(Commands, BuildVersionCommand())
 	Commands = append(Commands, BuildHelpCommand())
+	Commands = append(Commands, BuildOutlineCommand())
 }
 
 func main() {

ginkgo/outline/_testdata/alias_test.go

@@ -0,0 +1,49 @@
+package example_test
+
+import (
+	fooginkgo "github.com/onsi/ginkgo"
+)
+
+var _ = fooginkgo.Describe("NodotFixture", func() {
+	fooginkgo.Describe("normal", func() {
+		fooginkgo.It("normal", func() {
+			fooginkgo.By("normal")
+			fooginkgo.By("normal")
+
+		})
+	})
+
+	fooginkgo.Context("normal", func() {
+		fooginkgo.It("normal", func() {
+
+		})
+	})
+
+	fooginkgo.When("normal", func() {
+		fooginkgo.It("normal", func() {
+
+		})
+	})
+
+	fooginkgo.It("normal", func() {
+
+	})
+
+	fooginkgo.Specify("normal", func() {
+
+	})
+
+	fooginkgo.Measure("normal", func(b Benchmarker) {
+
+	}, 2)
+
+	fooginkgo.DescribeTable("normal",
+		func() {},
+		fooginkgo.Entry("normal"),
+	)
+
+	fooginkgo.DescribeTable("normal",
+		func() {},
+		fooginkgo.Entry("normal"),
+	)
+})

ginkgo/outline/_testdata/alias_test.go.csv

@@ -0,0 +1,13 @@
+Name,Text,Start,End,Spec,Focused,Pending
+Describe,NodotFixture,79,728,false,false,false
+Describe,normal,124,257,false,false,false
+It,normal,164,253,true,false,false
+By,normal,199,221,false,false,false
+By,normal,225,247,false,false,false
+Context,normal,260,340,false,false,false
+It,normal,299,336,true,false,false
+When,normal,343,420,false,false,false
+It,normal,379,416,true,false,false
+It,normal,423,459,true,false,false
+Specify,normal,462,503,true,false,false
+Measure,normal,506,563,true,false,false

ginkgo/outline/_testdata/alias_test.go.json

@@ -0,0 +1 @@
+[{"name":"Describe","text":"NodotFixture","start":79,"end":728,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"Describe","text":"normal","start":124,"end":257,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"normal","start":164,"end":253,"spec":true,"focused":false,"pending":false,"nodes":[{"name":"By","text":"normal","start":199,"end":221,"spec":false,"focused":false,"pending":false},{"name":"By","text":"normal","start":225,"end":247,"spec":false,"focused":false,"pending":false}]}]},{"name":"Context","text":"normal","start":260,"end":340,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"normal","start":299,"end":336,"spec":true,"focused":false,"pending":false}]},{"name":"When","text":"normal","start":343,"end":420,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"normal","start":379,"end":416,"spec":true,"focused":false,"pending":false}]},{"name":"It","text":"normal","start":423,"end":459,"spec":true,"focused":false,"pending":false},{"name":"Specify","text":"normal","start":462,"end":503,"spec":true,"focused":false,"pending":false},{"name":"Measure","text":"normal","start":506,"end":563,"spec":true,"focused":false,"pending":false}]}]

ginkgo/outline/_testdata/create_result.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -o errexit
+set -o nounset
+
+GINKGO=${GINKGO:-ginkgo}
+
+input=${1:-""}
+for format in "csv" "json"; do
+    set -o xtrace
+    output="$(dirname $input)/$(basename $input).$format"
+    tmp=$(mktemp ginkgo-outline-test.XXX)
+    if "$GINKGO" outline --format="$format" "$input" 1>"$tmp"
+    then mv "$tmp" "$output"
+    else rm "$tmp"
+    set +o xtrace
+    fi
+done

ginkgo/outline/_testdata/focused_test.go

@@ -0,0 +1,49 @@
+package example_test
+
+import (
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/ginkgo/extensions/table"
+)
+
+var _ = Describe("unfocused", func() {
+	FDescribe("focused", func() {
+		It("focused", func() {
+			By("focused")
+			By("focused")
+		})
+	})
+
+	FContext("focused", func() {
+		It("focused", func() {
+
+		})
+	})
+
+	FWhen("focused", func() {
+		It("focused", func() {
+
+		})
+	})
+
+	FIt("focused", func() {
+
+	})
+
+	FSpecify("focused", func() {
+
+	})
+
+	FMeasure("focused", func(b Benchmarker) {
+
+	}, 2)
+
+	FDescribeTable("focused",
+		func() {},
+		Entry("focused"),
+	)
+
+	DescribeTable("focused",
+		func() {},
+		FEntry("focused"),
+	)
+})

ginkgo/outline/_testdata/focused_test.go.csv

@@ -0,0 +1,13 @@
+Name,Text,Start,End,Spec,Focused,Pending
+Describe,unfocused,116,624,false,false,false
+FDescribe,focused,148,245,false,true,false
+It,focused,180,241,true,true,false
+By,focused,206,219,false,true,false
+By,focused,223,236,false,true,false
+FContext,focused,248,311,false,true,false
+It,focused,279,307,true,true,false
+FWhen,focused,314,374,false,true,false
+It,focused,342,370,true,true,false
+FIt,focused,377,405,true,true,false
+FSpecify,focused,408,441,true,true,false
+FMeasure,focused,444,493,true,true,false

ginkgo/outline/_testdata/focused_test.go.json

@@ -0,0 +1 @@
+[{"name":"Describe","text":"unfocused","start":116,"end":624,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"FDescribe","text":"focused","start":148,"end":245,"spec":false,"focused":true,"pending":false,"nodes":[{"name":"It","text":"focused","start":180,"end":241,"spec":true,"focused":true,"pending":false,"nodes":[{"name":"By","text":"focused","start":206,"end":219,"spec":false,"focused":true,"pending":false},{"name":"By","text":"focused","start":223,"end":236,"spec":false,"focused":true,"pending":false}]}]},{"name":"FContext","text":"focused","start":248,"end":311,"spec":false,"focused":true,"pending":false,"nodes":[{"name":"It","text":"focused","start":279,"end":307,"spec":true,"focused":true,"pending":false}]},{"name":"FWhen","text":"focused","start":314,"end":374,"spec":false,"focused":true,"pending":false,"nodes":[{"name":"It","text":"focused","start":342,"end":370,"spec":true,"focused":true,"pending":false}]},{"name":"FIt","text":"focused","start":377,"end":405,"spec":true,"focused":true,"pending":false},{"name":"FSpecify","text":"focused","start":408,"end":441,"spec":true,"focused":true,"pending":false},{"name":"FMeasure","text":"focused","start":444,"end":493,"spec":true,"focused":true,"pending":false}]}]

ginkgo/outline/_testdata/mixed_test.go

@@ -0,0 +1,45 @@
+package example_test
+
+import (
+	. "github.com/onsi/ginkgo"
+)
+
+var _ = FDescribe("unfocused", func() {
+	FContext("unfocused", func() {
+		It("unfocused", func() {
+
+		})
+		FIt("focused", func() {
+
+		})
+	})
+
+	Context("unfocused", func() {
+		FIt("focused", func() {
+
+		})
+		It("unfocused", func() {
+
+		})
+	})
+
+	FContext("focused", func() {
+		It("focused", func() {
+
+		})
+		It("focused", func() {
+
+		})
+	})
+
+	PContext("unfocused", func() {
+		FIt("unfocused", func() {
+			By("unfocused")
+			By("unfocused")
+		})
+		It("unfocused", func() {
+			By("unfocused")
+			By("unfocused")
+		})
+	})
+})

ginkgo/outline/_testdata/mixed_test.go.csv

@@ -0,0 +1,18 @@
+Name,Text,Start,End,Spec,Focused,Pending
+FDescribe,unfocused,71,582,false,false,false
+FContext,unfocused,104,203,false,false,false
+It,unfocused,137,167,true,false,false
+FIt,focused,170,199,true,true,false
+Context,unfocused,206,304,false,false,false
+FIt,focused,238,267,true,true,false
+It,unfocused,270,300,true,false,false
+FContext,focused,307,401,false,true,false
+It,focused,338,366,true,true,false
+It,focused,369,397,true,true,false
+PContext,unfocused,404,579,false,false,true
+FIt,unfocused,437,505,true,false,true
+By,unfocused,466,481,false,false,true
+By,unfocused,485,500,false,false,true
+It,unfocused,508,575,true,false,true
+By,unfocused,536,551,false,false,true
+By,unfocused,555,570,false,false,true

ginkgo/outline/_testdata/mixed_test.go.json

@@ -0,0 +1 @@
+[{"name":"FDescribe","text":"unfocused","start":71,"end":582,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"FContext","text":"unfocused","start":104,"end":203,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"unfocused","start":137,"end":167,"spec":true,"focused":false,"pending":false},{"name":"FIt","text":"focused","start":170,"end":199,"spec":true,"focused":true,"pending":false}]},{"name":"Context","text":"unfocused","start":206,"end":304,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"FIt","text":"focused","start":238,"end":267,"spec":true,"focused":true,"pending":false},{"name":"It","text":"unfocused","start":270,"end":300,"spec":true,"focused":false,"pending":false}]},{"name":"FContext","text":"focused","start":307,"end":401,"spec":false,"focused":true,"pending":false,"nodes":[{"name":"It","text":"focused","start":338,"end":366,"spec":true,"focused":true,"pending":false},{"name":"It","text":"focused","start":369,"end":397,"spec":true,"focused":true,"pending":false}]},{"name":"PContext","text":"unfocused","start":404,"end":579,"spec":false,"focused":false,"pending":true,"nodes":[{"name":"FIt","text":"unfocused","start":437,"end":505,"spec":true,"focused":false,"pending":true,"nodes":[{"name":"By","text":"unfocused","start":466,"end":481,"spec":false,"focused":false,"pending":true},{"name":"By","text":"unfocused","start":485,"end":500,"spec":false,"focused":false,"pending":true}]},{"name":"It","text":"unfocused","start":508,"end":575,"spec":true,"focused":false,"pending":true,"nodes":[{"name":"By","text":"unfocused","start":536,"end":551,"spec":false,"focused":false,"pending":true},{"name":"By","text":"unfocused","start":555,"end":570,"spec":false,"focused":false,"pending":true}]}]}]}]

ginkgo/outline/_testdata/nestedfocused_test.go

@@ -0,0 +1,36 @@
+package example_test
+
+import (
+	. "github.com/onsi/ginkgo"
+)
+
+var _ = FDescribe("unfocused", func() {
+	FContext("unfocused", func() {
+		It("unfocused", func() {
+			By("unfocused")
+			By("unfocused")
+		})
+		FIt("focused", func() {
+			By("focused")
+			By("focused")
+		})
+	})
+
+	Context("unfocused", func() {
+		FIt("focused", func() {
+
+		})
+		It("unfocused", func() {
+
+		})
+	})
+
+	FContext("focused", func() {
+		It("focused", func() {
+
+		})
+		It("focused", func() {
+
+		})
+	})
+})

ginkgo/outline/_testdata/nestedfocused_test.go.csv

@@ -0,0 +1,15 @@
+Name,Text,Start,End,Spec,Focused,Pending
+FDescribe,unfocused,71,474,false,false,false
+FContext,unfocused,104,273,false,false,false
+It,unfocused,137,204,true,false,false
+By,unfocused,165,180,false,false,false
+By,unfocused,184,199,false,false,false
+FIt,focused,207,269,true,true,false
+By,focused,234,247,false,true,false
+By,focused,251,264,false,true,false
+Context,unfocused,276,374,false,false,false
+FIt,focused,308,337,true,true,false
+It,unfocused,340,370,true,false,false
+FContext,focused,377,471,false,true,false
+It,focused,408,436,true,true,false
+It,focused,439,467,true,true,false

ginkgo/outline/_testdata/nestedfocused_test.go.json

@@ -0,0 +1 @@
+[{"name":"FDescribe","text":"unfocused","start":71,"end":474,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"FContext","text":"unfocused","start":104,"end":273,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"unfocused","start":137,"end":204,"spec":true,"focused":false,"pending":false,"nodes":[{"name":"By","text":"unfocused","start":165,"end":180,"spec":false,"focused":false,"pending":false},{"name":"By","text":"unfocused","start":184,"end":199,"spec":false,"focused":false,"pending":false}]},{"name":"FIt","text":"focused","start":207,"end":269,"spec":true,"focused":true,"pending":false,"nodes":[{"name":"By","text":"focused","start":234,"end":247,"spec":false,"focused":true,"pending":false},{"name":"By","text":"focused","start":251,"end":264,"spec":false,"focused":true,"pending":false}]}]},{"name":"Context","text":"unfocused","start":276,"end":374,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"FIt","text":"focused","start":308,"end":337,"spec":true,"focused":true,"pending":false},{"name":"It","text":"unfocused","start":340,"end":370,"spec":true,"focused":false,"pending":false}]},{"name":"FContext","text":"focused","start":377,"end":471,"spec":false,"focused":true,"pending":false,"nodes":[{"name":"It","text":"focused","start":408,"end":436,"spec":true,"focused":true,"pending":false},{"name":"It","text":"focused","start":439,"end":467,"spec":true,"focused":true,"pending":false}]}]}]

ginkgo/outline/_testdata/nodot_test.go

@@ -0,0 +1,48 @@
+package example_test
+
+import (
+	"github.com/onsi/ginkgo"
+)
+
+var _ = ginkgo.Describe("NodotFixture", func() {
+	ginkgo.Describe("normal", func() {
+		ginkgo.It("normal", func() {
+			ginkgo.By("normal")
+			ginkgo.By("normal")
+		})
+	})
+
+	ginkgo.Context("normal", func() {
+		ginkgo.It("normal", func() {
+
+		})
+	})
+
+	ginkgo.When("normal", func() {
+		ginkgo.It("normal", func() {
+
+		})
+	})
+
+	ginkgo.It("normal", func() {
+
+	})
+
+	ginkgo.Specify("normal", func() {
+
+	})
+
+	ginkgo.Measure("normal", func(b Benchmarker) {
+
+	}, 2)
+
+	ginkgo.DescribeTable("normal",
+		func() {},
+		ginkgo.Entry("normal"),
+	)
+
+	ginkgo.DescribeTable("normal",
+		func() {},
+		ginkgo.Entry("normal"),
+	)
+})

ginkgo/outline/_testdata/nodot_test.go.csv

@@ -0,0 +1,13 @@
+Name,Text,Start,End,Spec,Focused,Pending
+Describe,NodotFixture,69,669,false,false,false
+Describe,normal,111,231,false,false,false
+It,normal,148,227,true,false,false
+By,normal,180,199,false,false,false
+By,normal,203,222,false,false,false
+Context,normal,234,308,false,false,false
+It,normal,270,304,true,false,false
+When,normal,311,382,false,false,false
+It,normal,344,378,true,false,false
+It,normal,385,418,true,false,false
+Specify,normal,421,459,true,false,false
+Measure,normal,462,516,true,false,false

ginkgo/outline/_testdata/nodot_test.go.json

@@ -0,0 +1 @@
+[{"name":"Describe","text":"NodotFixture","start":69,"end":669,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"Describe","text":"normal","start":111,"end":231,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"normal","start":148,"end":227,"spec":true,"focused":false,"pending":false,"nodes":[{"name":"By","text":"normal","start":180,"end":199,"spec":false,"focused":false,"pending":false},{"name":"By","text":"normal","start":203,"end":222,"spec":false,"focused":false,"pending":false}]}]},{"name":"Context","text":"normal","start":234,"end":308,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"normal","start":270,"end":304,"spec":true,"focused":false,"pending":false}]},{"name":"When","text":"normal","start":311,"end":382,"spec":false,"focused":false,"pending":false,"nodes":[{"name":"It","text":"normal","start":344,"end":378,"spec":true,"focused":false,"pending":false}]},{"name":"It","text":"normal","start":385,"end":418,"spec":true,"focused":false,"pending":false},{"name":"Specify","text":"normal","start":421,"end":459,"spec":true,"focused":false,"pending":false},{"name":"Measure","text":"normal","start":462,"end":516,"spec":true,"focused":false,"pending":false}]}]