Expand GinkgoT() to include several Ginkgo-specific methods

this enables authors of third party libraries to have a richer integration point with Ginkgo

Author: onsi

core_dsl.go

@@ -540,7 +540,7 @@ and will simply log the passed in text to the GinkgoWriter.  If By is handed a f
 
 By will also generate and attach a ReportEntry to the spec.  This will ensure that By annotations appear in Ginkgo's machine-readable reports.
 
-Note that By does not generate a new Ginkgo node - rather it is simply synctactic sugar around GinkgoWriter and AddReportEntry
+Note that By does not generate a new Ginkgo node - rather it is simply syntactic sugar around GinkgoWriter and AddReportEntry
 You can learn more about By here: https://onsi.github.io/ginkgo/#documenting-complex-specs-by
 */
 func By(text string, callback ...func()) {

docs/index.md

@@ -5340,6 +5340,8 @@ Since `GinkgoT()` implements `Cleanup()` (using `DeferCleanup()` under the hood)
 
 When using Gomock you may want to run `ginkgo` with the `-trace` flag to print out stack traces for failures which will help you trace down where, in your code, invalid calls occurred.
 
+`GinkgoT()` also provides additional methods that are Ginkgo-specific.  This allows rich third-party integrations to be built on top of Ginkgo - with GinkgoT() serving as a single connection point.
+
 ### IDE Support
 Ginkgo works best from the command-line, and [`ginkgo watch`](#watching-for-changes) makes it easy to rerun tests on the command line whenever changes are detected.
 

dsl/core/core_dsl.go

@@ -21,6 +21,7 @@ const GINKGO_VERSION = ginkgo.GINKGO_VERSION
 type GinkgoWriterInterface = ginkgo.GinkgoWriterInterface
 type GinkgoTestingT = ginkgo.GinkgoTestingT
 type GinkgoTInterface = ginkgo.GinkgoTInterface
+type FullGinkgoTInterface = ginkgo.FullGinkgoTInterface
 type SpecContext = ginkgo.SpecContext
 
 var GinkgoWriter = ginkgo.GinkgoWriter

ginkgo_t_dsl.go

@@ -1,22 +1,38 @@
 package ginkgo
 
-import "github.com/onsi/ginkgo/v2/internal/testingtproxy"
+import (
+	"github.com/onsi/ginkgo/v2/internal/testingtproxy"
+)
 
 /*
-GinkgoT() implements an interface analogous to *testing.T and can be used with
-third-party libraries that accept *testing.T through an interface.
+GinkgoT() implements an interface that allows third party libraries to integrate with and build on top of Ginkgo.
+
+GinkgoT() is analogous to *testing.T and implements the majority of *testing.T's methods.  It can be typically be used a a drop-in replacement with third-party libraries that accept *testing.T through an interface.
 
 GinkgoT() takes an optional offset argument that can be used to get the
 correct line number associated with the failure - though you do not need to use this if you call GinkgoHelper() or GinkgoT().Helper() appropriately
 
 You can learn more here: https://onsi.github.io/ginkgo/#using-third-party-libraries
 */
-func GinkgoT(optionalOffset ...int) GinkgoTInterface {
+func GinkgoT(optionalOffset ...int) FullGinkgoTInterface {
 	offset := 3
 	if len(optionalOffset) > 0 {
 		offset = optionalOffset[0]
 	}
-	return testingtproxy.New(GinkgoWriter, Fail, Skip, DeferCleanup, CurrentSpecReport, offset)
+	return testingtproxy.New(
+		GinkgoWriter,
+		Fail,
+		Skip,
+		DeferCleanup,
+		CurrentSpecReport,
+		AddReportEntry,
+		GinkgoRecover,
+		AttachProgressReporter,
+		suiteConfig.RandomSeed,
+		suiteConfig.ParallelProcess,
+		suiteConfig.ParallelTotal,
+		reporterConfig.NoColor,
+		offset)
 }
 
 /*
@@ -43,3 +59,30 @@ type GinkgoTInterface interface {
 	Skipped() bool
 	TempDir() string
 }
+
+type FullGinkgoTInterface interface {
+	GinkgoTInterface
+
+	AddReportEntryVisibilityAlways(name string, args ...any)
+	AddReportEntryVisibilityFailureOrVerbose(name string, args ...any)
+	AddReportEntryVisibilityNever(name string, args ...any)
+
+	//Prints to the GinkgoWriter
+	Print(a ...interface{})
+	Printf(format string, a ...interface{})
+	Println(a ...interface{})
+
+	//Provides access to Ginkgo's color formatting, correctly configured to match the color settings specified in the invocation of ginkgo
+	F(format string, args ...any) string
+	Fi(indentation uint, format string, args ...any) string
+	Fiw(indentation uint, maxWidth uint, format string, args ...any) string
+
+	GinkgoRecover()
+	DeferCleanup(args ...any)
+
+	RandomSeed() int64
+	ParallelProcess() int
+	ParallelTotal() int
+
+	AttachProgressReporter(func() string) func()
+}

internal/testingtproxy/testing_t_proxy.go

@@ -5,34 +5,61 @@ import (
 	"io"
 	"os"
 
+	"github.com/onsi/ginkgo/v2/formatter"
 	"github.com/onsi/ginkgo/v2/internal"
 	"github.com/onsi/ginkgo/v2/types"
 )
 
 type failFunc func(message string, callerSkip ...int)
 type skipFunc func(message string, callerSkip ...int)
-type cleanupFunc func(args ...interface{})
+type cleanupFunc func(args ...any)
 type reportFunc func() types.SpecReport
+type addReportEntryFunc func(names string, args ...any)
+type ginkgoWriterInterface interface {
+	io.Writer
 
-func New(writer io.Writer, fail failFunc, skip skipFunc, cleanup cleanupFunc, report reportFunc, offset int) *ginkgoTestingTProxy {
+	Print(a ...interface{})
+	Printf(format string, a ...interface{})
+	Println(a ...interface{})
+}
+type ginkgoRecoverFunc func()
+type attachProgressReporterFunc func(func() string) func()
+
+func New(writer ginkgoWriterInterface, fail failFunc, skip skipFunc, cleanup cleanupFunc, report reportFunc, addReportEntry addReportEntryFunc, ginkgoRecover ginkgoRecoverFunc, attachProgressReporter attachProgressReporterFunc, randomSeed int64, parallelProcess int, parallelTotal int, noColor bool, offset int) *ginkgoTestingTProxy {
 	return &ginkgoTestingTProxy{
-		fail:    fail,
-		offset:  offset,
-		writer:  writer,
-		skip:    skip,
-		cleanup: cleanup,
-		report:  report,
+		fail:                   fail,
+		offset:                 offset,
+		writer:                 writer,
+		skip:                   skip,
+		cleanup:                cleanup,
+		report:                 report,
+		addReportEntry:         addReportEntry,
+		ginkgoRecover:          ginkgoRecover,
+		attachProgressReporter: attachProgressReporter,
+		randomSeed:             randomSeed,
+		parallelProcess:        parallelProcess,
+		parallelTotal:          parallelTotal,
+		f:                      formatter.NewWithNoColorBool(noColor),
 	}
 }
 
 type ginkgoTestingTProxy struct {
-	fail    failFunc
-	skip    skipFunc
-	cleanup cleanupFunc
-	report  reportFunc
-	offset  int
-	writer  io.Writer
-}
+	fail                   failFunc
+	skip                   skipFunc
+	cleanup                cleanupFunc
+	report                 reportFunc
+	offset                 int
+	writer                 ginkgoWriterInterface
+	addReportEntry         addReportEntryFunc
+	ginkgoRecover          ginkgoRecoverFunc
+	attachProgressReporter attachProgressReporterFunc
+	randomSeed             int64
+	parallelProcess        int
+	parallelTotal          int
+	f                      formatter.Formatter
+}
+
+// basic testing.T support
 
 func (t *ginkgoTestingTProxy) Cleanup(f func()) {
 	t.cleanup(f, internal.Offset(1))
@@ -126,3 +153,54 @@ func (t *ginkgoTestingTProxy) TempDir() string {
 
 	return tmpDir
 }
+
+// FullGinkgoTInterface
+func (t *ginkgoTestingTProxy) AddReportEntryVisibilityAlways(name string, args ...any) {
+	finalArgs := []any{internal.Offset(1), types.ReportEntryVisibilityAlways}
+	t.addReportEntry(name, append(finalArgs, args...)...)
+}
+func (t *ginkgoTestingTProxy) AddReportEntryVisibilityFailureOrVerbose(name string, args ...any) {
+	finalArgs := []any{internal.Offset(1), types.ReportEntryVisibilityFailureOrVerbose}
+	t.addReportEntry(name, append(finalArgs, args...)...)
+}
+func (t *ginkgoTestingTProxy) AddReportEntryVisibilityNever(name string, args ...any) {
+	finalArgs := []any{internal.Offset(1), types.ReportEntryVisibilityNever}
+	t.addReportEntry(name, append(finalArgs, args...)...)
+}
+func (t *ginkgoTestingTProxy) Print(a ...any) {
+	t.writer.Print(a...)
+}
+func (t *ginkgoTestingTProxy) Printf(format string, a ...any) {
+	t.writer.Printf(format, a...)
+}
+func (t *ginkgoTestingTProxy) Println(a ...any) {
+	t.writer.Println(a...)
+}
+func (t *ginkgoTestingTProxy) F(format string, args ...any) string {
+	return t.f.F(format, args...)
+}
+func (t *ginkgoTestingTProxy) Fi(indentation uint, format string, args ...any) string {
+	return t.f.Fi(indentation, format, args...)
+}
+func (t *ginkgoTestingTProxy) Fiw(indentation uint, maxWidth uint, format string, args ...any) string {
+	return t.f.Fiw(indentation, maxWidth, format, args...)
+}
+func (t *ginkgoTestingTProxy) GinkgoRecover() {
+	t.ginkgoRecover()
+}
+func (t *ginkgoTestingTProxy) DeferCleanup(args ...any) {
+	finalArgs := []any{internal.Offset(1)}
+	t.cleanup(append(finalArgs, args...)...)
+}
+func (t *ginkgoTestingTProxy) RandomSeed() int64 {
+	return t.randomSeed
+}
+func (t *ginkgoTestingTProxy) ParallelProcess() int {
+	return t.parallelProcess
+}
+func (t *ginkgoTestingTProxy) ParallelTotal() int {
+	return t.parallelTotal
+}
+func (t *ginkgoTestingTProxy) AttachProgressReporter(f func() string) func() {
+	return t.attachProgressReporter(f)
+}