1/*
  2
  3Table provides a simple DSL for Ginkgo-native Table-Driven Tests
  4
  5The godoc documentation describes Table's API.  More comprehensive documentation (with examples!) is available at http://onsi.github.io/ginkgo#table-driven-tests
  6
  7*/
  8
  9package table
 10
 11import (
 12	"fmt"
 13	"reflect"
 14
 15	"github.com/onsi/ginkgo/internal/codelocation"
 16	"github.com/onsi/ginkgo/internal/global"
 17	"github.com/onsi/ginkgo/types"
 18)
 19
 20/*
 21DescribeTable describes a table-driven test.
 22
 23For example:
 24
 25    DescribeTable("a simple table",
 26        func(x int, y int, expected bool) {
 27            Ω(x > y).Should(Equal(expected))
 28        },
 29        Entry("x > y", 1, 0, true),
 30        Entry("x == y", 0, 0, false),
 31        Entry("x < y", 0, 1, false),
 32    )
 33
 34The first argument to `DescribeTable` is a string description.
 35The second argument is a function that will be run for each table entry.  Your assertions go here - the function is equivalent to a Ginkgo It.
 36The subsequent arguments must be of type `TableEntry`.  We recommend using the `Entry` convenience constructors.
 37
 38The `Entry` constructor takes a string description followed by an arbitrary set of parameters.  These parameters are passed into your function.
 39
 40Under the hood, `DescribeTable` simply generates a new Ginkgo `Describe`.  Each `Entry` is turned into an `It` within the `Describe`.
 41
 42It's important to understand that the `Describe`s and `It`s are generated at evaluation time (i.e. when Ginkgo constructs the tree of tests and before the tests run).
 43
 44Individual Entries can be focused (with FEntry) or marked pending (with PEntry or XEntry).  In addition, the entire table can be focused or marked pending with FDescribeTable and PDescribeTable/XDescribeTable.
 45
 46A description function can be passed to Entry in place of the description. The function is then fed with the entry parameters to generate the description of the It corresponding to that particular Entry.
 47
 48For example:
 49
 50	describe := func(desc string) func(int, int, bool) string {
 51		return func(x, y int, expected bool) string {
 52			return fmt.Sprintf("%s x=%d y=%d expected:%t", desc, x, y, expected)
 53		}
 54	}
 55
 56	DescribeTable("a simple table",
 57		func(x int, y int, expected bool) {
 58			Ω(x > y).Should(Equal(expected))
 59		},
 60		Entry(describe("x > y"), 1, 0, true),
 61		Entry(describe("x == y"), 0, 0, false),
 62		Entry(describe("x < y"), 0, 1, false),
 63	)
 64*/
 65func DescribeTable(description string, itBody interface{}, entries ...TableEntry) bool {
 66	describeTable(description, itBody, entries, types.FlagTypeNone)
 67	return true
 68}
 69
 70/*
 71You can focus a table with `FDescribeTable`.  This is equivalent to `FDescribe`.
 72*/
 73func FDescribeTable(description string, itBody interface{}, entries ...TableEntry) bool {
 74	describeTable(description, itBody, entries, types.FlagTypeFocused)
 75	return true
 76}
 77
 78/*
 79You can mark a table as pending with `PDescribeTable`.  This is equivalent to `PDescribe`.
 80*/
 81func PDescribeTable(description string, itBody interface{}, entries ...TableEntry) bool {
 82	describeTable(description, itBody, entries, types.FlagTypePending)
 83	return true
 84}
 85
 86/*
 87You can mark a table as pending with `XDescribeTable`.  This is equivalent to `XDescribe`.
 88*/
 89func XDescribeTable(description string, itBody interface{}, entries ...TableEntry) bool {
 90	describeTable(description, itBody, entries, types.FlagTypePending)
 91	return true
 92}
 93
 94func describeTable(description string, itBody interface{}, entries []TableEntry, flag types.FlagType) {
 95	itBodyValue := reflect.ValueOf(itBody)
 96	if itBodyValue.Kind() != reflect.Func {
 97		panic(fmt.Sprintf("DescribeTable expects a function, got %#v", itBody))
 98	}
 99
100	global.Suite.PushContainerNode(
101		description,
102		func() {
103			for _, entry := range entries {
104				entry.generateIt(itBodyValue)
105			}
106		},
107		flag,
108		codelocation.New(2),
109	)
110}