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

dlipovetsky · 2020-12-26T05:30:24Z

Why this PR is needed:
Implements feature request in #753.

Please see the test fixtures for example CSV and JSON output.

Special notes:
There are a couple of TODOs in the code, and I'll call them out here:

Aliased and nodot imports are not yet supported.
The Focus property is derived only from the container or spec name. It is not inherited from an outer container. Also, the focusing behavior described in the docs (and implemented here) is not yet supported:

Nested programmatically focused specs follow a simple rule: if
a leaf-node is marked focused, any of its ancestor nodes that
are marked focus will be unfocused.

…file Implements feature request in onsi#753

dlipovetsky · 2020-12-26T17:37:08Z

First CI run failed all jobs, because I hadn't run go mod tidy before committing. I ran locally and amended.

Second CI run failed just the "tip" job, because that version of go mod wanted to remove some more entries from go.sum. I removed those by hand locally and amended.

dlipovetsky · 2020-12-26T17:48:23Z

Third CI run failed just the "tip" job. Looks unrelated to my changes:

• Failure [30.014 seconds]

Running Specs when passed a number of packages to run [It] should run the ginkgo style tests 

/home/travis/gopath/src/github.com/onsi/ginkgo/integration/run_test.go:72

  Timed out after 30.001s.

  Expected process to exit.  It did not.

  /home/travis/gopath/src/github.com/onsi/ginkgo/integration/run_test.go:74

onsi · 2020-12-26T19:47:55Z

Thanks @dlipovetsky - this is super exciting! I'll take a look in the next few days. I suspect the integration test is flaky (possibly because of a change in go tip, but more likely it's just flakey and the travis worker it was on was slow).

…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.

…us/pending properties

…t results To make it easier to maintain the outline tests.

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

The top-level function needed to be shorter.

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

Keep the unexprted ginkgoNode code in a separate file.

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

The "text" was being ignored by mistake.

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

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 ```

dlipovetsky · 2020-12-29T06:53:45Z

ginkgo/outline/import.go

@@ -0,0 +1,61 @@
+// Copyright 2013 The Go Authors. All rights reserved.


Let me know if you see any problem with copy/pasting upstream code here. I've kept the upstream license, and noted the source commit.

dlipovetsky · 2020-12-29T06:55:36Z

ginkgo/outline/ginkgo.go

+// > leaf-node is marked focused, any of its ancestor nodes that are marked
+// > focus will be unfocused.
+func (n *ginkgoNode) BackpropagateUnfocus() {
+	focusedSpecInSubtreeStack := []bool{}


This is hard to understand. I need to add some explanatory comments, and probably a unit test.

the whole back propagate thing is intrinsically complex! thanks for making this work!!

dlipovetsky · 2020-12-29T06:57:27Z

ginkgo/outline/outline.go

+			if !ok {
+				// Because `Nodes` calls this function only when the node is an
+				// ast.CallExpr, this should never happen
+				panic(fmt.Errorf("node starting at %d, ending at %d is not an *ast.CallExpr", node.Pos(), node.End()))


Not sure if panicking is the only option. This is supposed to be impossible to reach.

dlipovetsky · 2020-12-29T06:59:52Z

ginkgo/outline/outline.go

+	currentIndent := 0
+	pre := func(n *ginkgoNode) {
+		b.WriteString(fmt.Sprintf("%*s", currentIndent, ""))
+		b.WriteString(fmt.Sprintf("%s,%s,%d,%d,%t,%t,%t\n", n.Name, n.Text, n.Start, n.End, n.Spec, n.Focused, n.Pending))


I considered moving this to a ginkgoNode.String() receiver, but because most of the work is "opinionated" formatting, I thought it best not to put it there.

onsi · 2020-12-30T22:53:00Z

@dlipovetsky this is amazing, thanks so much! I'm going to merge this in. Would you be up for updating the documentation on the gh-pages branch and I can pull that in as well? Just a simple description of the command would be enough imo.

I may do a bit of clean-up and move the tests over to the integration test suite. But I didn't want to delay so am pulling this in now! Thanks so much!!

dlipovetsky · 2020-12-31T06:14:40Z

Would you be up for updating the documentation on the gh-pages branch and I can pull that in as well? Just a simple description of the command would be enough imo.

Will do!

I may do a bit of clean-up and move the tests over to the integration test suite.

That sounds right. Thanks!

The `ginkgo outline` command was added in onsi#754.

The `ginkgo outline` command was added in #754.

dlipovetsky force-pushed the outline branch from 6347299 to 3be1637 Compare December 26, 2020 16:55

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

c386859

…file Implements feature request in onsi#753

dlipovetsky force-pushed the outline branch from 3be1637 to c386859 Compare December 26, 2020 17:34

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

bdc78da

dlipovetsky force-pushed the outline branch from 5ff68c9 to bdc78da Compare December 26, 2020 23:53

dlipovetsky added 11 commits December 28, 2020 20:43

outline: Add backpropagation of unfocus, propagation of inherited foc…

a629f65

…us/pending properties

outline: Add instructions and script for creating/updating sample tes…

c85d63e

…t results To make it easier to maintain the outline tests.

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

245e360

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

outline: Factor the back/propagation code to helper functions

144c847

The top-level function needed to be shorter.

outline: Refactor deriving ginkgo identifier from call expression

a717abc

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

outline: Move the exported outline code into its own file

380e88f

Keep the unexprted ginkgoNode code in a separate file.

outline: Instead of aliasing ginkgoNode with outline, embed ginkgoNod…

4317c54

…e 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

2ca52da

The "text" was being ignored by mistake.

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

bc67def

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

dlipovetsky commented Dec 29, 2020

View reviewed changes

onsi merged commit 071c369 into onsi:master Dec 30, 2020

dlipovetsky added a commit to dlipovetsky/ginkgo that referenced this pull request Dec 31, 2020

Document the ginkgo outline command

bedb1a9

The `ginkgo outline` command was added in onsi#754.

This was referenced Dec 31, 2020

Document the ginkgo outline command #757

Merged

Output spec type, name, and codelocation - for use by an IDE #753

Closed

onsi pushed a commit that referenced this pull request Dec 31, 2020

Document the ginkgo outline command (#757)

0939df8

The `ginkgo outline` command was added in #754.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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 #754

dlipovetsky commented Dec 26, 2020 •

edited

dlipovetsky commented Dec 26, 2020

dlipovetsky commented Dec 26, 2020

onsi commented Dec 26, 2020

dlipovetsky Dec 29, 2020 •

edited

dlipovetsky Dec 29, 2020

onsi Dec 30, 2020

dlipovetsky Dec 29, 2020

dlipovetsky Dec 29, 2020

onsi commented Dec 30, 2020

dlipovetsky commented Dec 31, 2020

		@@ -0,0 +1,61 @@
		// Copyright 2013 The Go Authors. All rights reserved.

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 #754

Conversation

dlipovetsky commented Dec 26, 2020 • edited

dlipovetsky commented Dec 26, 2020

dlipovetsky commented Dec 26, 2020

onsi commented Dec 26, 2020

dlipovetsky Dec 29, 2020 • edited

Choose a reason for hiding this comment

dlipovetsky Dec 29, 2020

Choose a reason for hiding this comment

onsi Dec 30, 2020

Choose a reason for hiding this comment

dlipovetsky Dec 29, 2020

Choose a reason for hiding this comment

dlipovetsky Dec 29, 2020

Choose a reason for hiding this comment

onsi commented Dec 30, 2020

dlipovetsky commented Dec 31, 2020

dlipovetsky commented Dec 26, 2020 •

edited

dlipovetsky Dec 29, 2020 •

edited