testcase

package
v1.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 15, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsValidTestCase

func IsValidTestCase(funcDecl *dst.FuncDecl) (valid bool, badFormat bool)

Determine if the given function declaration is a valid test case. Returns two booleans: `valid` indicating whether this is a valid test case, and `badFormat` indicating whether the test case has an incorrect (but acceptable) format. `badFormat` is false if the function is not valid.

The test case is validated using the following criteria: - The function name starts with "Test" followed by a capital letter - The function has `*testing.T` as its only formal parameter - The function does not have any receiver (i.e., it is not a method) - The function does not have any generic type parameters - The function does not return any values

Types

type AnalysisResult

type AnalysisResult struct {
	// Reference to the original test case being analyzed
	TestCase *TestCase

	// Analysis data
	ScenarioSet      *ScenarioSet         // the set of scenarios defined in this test case, if it is table-driven
	ParsedStatements []*ExpandedStatement // the list of parsed and fully-expanded statements in the test case
	ImportedPackages []string             // the list of imported packages in the test case's file

	// Refactoring result - only available after running `AttemptRefactoring()`
	RefactorResult RefactorResult // the result of refactoring the test case
}

Represents the result of analyzing a TestCase, including information about its table-driven structure.

func Analyze

func Analyze(tc *TestCase) *AnalysisResult

Extracts relevant information about a TestCase and saves the results to a new AnalysisResult instance

func (*AnalysisResult) AttemptRefactoring

func (ar *AnalysisResult) AttemptRefactoring(strategy RefactorStrategy, keepRefactoredFiles bool) RefactorResult

Attempts to refactor a test case using the specified strategy. If a refactoring is successfully generated, the test is executed using the original and refactored code. The default behavior is to restore the original file contents after the refactoring is complete, but this can be disabled by setting `keepRefactoredFiles` to true. Saves the result of the refactoring attempt to the AnalysisResult, and also returns a copy of the result.

func (*AnalysisResult) EncodeAsCSV

func (ar *AnalysisResult) EncodeAsCSV() []string

Encode the AnalysisResult as a CSV row, returning the encoded data corresponding to the headers in `GetCSVHeaders()`.

func (*AnalysisResult) GetCSVHeaders

func (ar *AnalysisResult) GetCSVHeaders() []string

Return the headers for the CSV representation of the AnalysisResult. Complex or large fields are excluded for the sake of brevity.

func (*AnalysisResult) IsTableDriven

func (ar *AnalysisResult) IsTableDriven() bool

Return whether the test case is table-driven, based on the detected ScenarioSet data

func (*AnalysisResult) SaveAsJSON

func (ar *AnalysisResult) SaveAsJSON(dir string) error

Save the AnalysisResult as JSON to a file named like `<project>/<project>_<package>_<testName>.json` in the specified directory (or the output directory if not specified).

type ExpandedStatement

type ExpandedStatement struct {
	// The original statement
	Stmt dst.Stmt

	// The expanded form of the called function's inner statements, or nil if the statement is not a function call
	Children []*ExpandedStatement
}

Represents the expanded form of a function call statement as a G-tree. If the statement is a function call, its inner statements are expanded recursively and stored in `Children`. If the statement involves function calls somehow (e.g. as part of an assignment or conditional statement), those calls are also considered as children. If the statement is not a function call and does not involve any function calls, its `Children` field is nil.

func ExpandStatement

func ExpandStatement(stmt dst.Stmt, tc *TestCase, testOnly bool) *ExpandedStatement

Recursively create the fully expanded form of a function call statement, expanding depth first. If `testOnly` is true, only expand statements that are defined in a file with a `_test.go` suffix. Note that functions are only expanded when they're called, so function literals (e.g. inside `t.Run()`) are not expanded.

func (*ExpandedStatement) All

func (es *ExpandedStatement) All() iter.Seq[dst.Stmt]

Returns an iterator over all the statements contained within the ExpandedStatement

func (*ExpandedStatement) MarshalJSON

func (es *ExpandedStatement) MarshalJSON() ([]byte, error)

Marshal a TestCase for JSON output

func (*ExpandedStatement) String

func (es *ExpandedStatement) String() string

Return a string representation of an expanded statement, including the stringified versions of its children.

func (*ExpandedStatement) UnmarshalJSON

func (es *ExpandedStatement) UnmarshalJSON(data []byte) error

Unmarshal a TestCase from JSON

type ExpressionDefinition

type ExpressionDefinition struct {
	// The DST node representing the actual expression definition
	Node dst.Node

	// The DST file that contains the definition, or nil if it was not found
	File *dst.File
}

Represents the definition of an expression as found by FindDefinition.

func FindDefinition

func FindDefinition(expr dst.Expr, tc *TestCase, testOnly bool) (*ExpressionDefinition, error)

Return the DST definition and of the expression within the specified TestCase's package, if it exists. Also returns the DST file that contains the definition if it is successfully found, or nil in all other cases. If the expression is not an identifier or selector expression, returns the original expression. Returns nil for both return values (indicating that the definition was deliberately excluded) in the following cases:

  • The expression is not defined in the specified context package
  • If `testOnly` is true and the expression is not defined in a file with a `_test.go` suffix

type RefactorGenerationStatus

type RefactorGenerationStatus int

Represents the status of an attempt to generate refactored code for a test case.

const (
	RefactorGenerationStatusNone      RefactorGenerationStatus = iota // No refactoring was attempted
	RefactorGenerationStatusError                                     // Refactoring could not be performed properly due to an unrecoverable error, e.g. due to a logic error
	RefactorGenerationStatusBadFields                                 // Refactoring failed based on the configuration of the scenario fields
	RefactorGenerationStatusNoTester                                  // Refactoring failed because a `*testing.T` variable could not be detected
	RefactorGenerationStatusFail                                      // Refactoring failed unexpectedly, e.g. due to an unusual AST structure
	RefactorGenerationStatusSuccess                                   // Refactoring was successful
)

func (RefactorGenerationStatus) MarshalJSON

func (rs RefactorGenerationStatus) MarshalJSON() ([]byte, error)

func (RefactorGenerationStatus) String

func (rs RefactorGenerationStatus) String() string

func (*RefactorGenerationStatus) UnmarshalJSON

func (rs *RefactorGenerationStatus) UnmarshalJSON(data []byte) error

type RefactorResult

type RefactorResult struct {
	// The refactoring strategy that was applied, if any
	Strategy RefactorStrategy `json:"strategy"`

	// The status of the refactor generation attempt
	GenerationStatus RefactorGenerationStatus `json:"status"`

	// The contents of the refactored test case, if the refactor generation was successful
	Refactorings []RefactoredFunction `json:"refactorings"`

	// The results of executing the test case before and after refactoring
	OriginalExecutionResult   TestExecutionResult `json:"originalTestResult"`
	RefactoredExecutionResult TestExecutionResult `json:"refactoredTestResult"`
}

Represents the result of a refactoring attempt on a test case.

type RefactorStrategy

type RefactorStrategy int

Represents a refactoring strategy that can be applied to a test case. Each value corresponds to a refactoring method with a similar name.

const (
	RefactorStrategyNone    RefactorStrategy = iota // No refactoring method specified
	RefactorStrategySubtest                         // Wrap the entire contents of the execution loop in a call to `t.Run()`
)

func RefactorStrategyFromString

func RefactorStrategyFromString(method string) RefactorStrategy

Return the RefactorStrategy corresponding to the given string.

func (RefactorStrategy) MarshalJSON

func (rm RefactorStrategy) MarshalJSON() ([]byte, error)

func (RefactorStrategy) String

func (rm RefactorStrategy) String() string

func (*RefactorStrategy) UnmarshalJSON

func (rm *RefactorStrategy) UnmarshalJSON(data []byte) error

type RefactoredFunction

type RefactoredFunction struct {
	Refactored       *dst.FuncDecl `json:"-"`          // The actual refactored function declaration
	RefactoredString string        `json:"refactored"` // The string representation of the refactored function declaration

	File     *dst.File `json:"-"`        // The DST file where the refactored function is defined
	FilePath string    `json:"filePath"` // The path to the file containing the refactored function
	IsHelper bool      `json:"isHelper"` // Whether this function is a helper function rather than the test function itself
	// contains filtered or unexported fields
}

Represents function declaration that has been refactored. Note that the DST file is not guaranteed to retain the modified function data after Cleanup is called, but it should still be retained by the FuncDecl reference (and by the string forms of these DST elements).

func NewRefactoredFunction

func NewRefactoredFunction(fn *dst.FuncDecl, file *dst.File, filePath string, isHelper bool, cleanupFunc func() error) *RefactoredFunction

Creates a new RefactoredFunction with the provided DST data.

func (*RefactoredFunction) Cleanup

func (rf *RefactoredFunction) Cleanup()

Cleans up the refactored function by restoring the original DST function declaration, if possible. Does not affect the file on the disk.

func (*RefactoredFunction) UpdateStringRepresentation

func (rf *RefactoredFunction) UpdateStringRepresentation()

Performs an in-place update of the string representation of the refactored DST function declaration.

type Scenario

type Scenario struct {
	Name string // the detected name of the scenario, either from a "name" or "desc" field, or the key of a map

	Expr dst.Expr
}

Represents an individual scenario defined by a table-driven test todo LATER not implemented yet

type ScenarioDataStructure

type ScenarioDataStructure int

Represents the type of data structure used to store scenarios

const (
	ScenarioNoDS         ScenarioDataStructure = iota // no table-driven test structure detected
	ScenarioStructListDS                              // table-driven test using a slice or array of structs
	ScenarioMapDS                                     // table-driven test using a map
)

func (ScenarioDataStructure) MarshalJSON

func (sds ScenarioDataStructure) MarshalJSON() ([]byte, error)

func (ScenarioDataStructure) String

func (sds ScenarioDataStructure) String() string

func (*ScenarioDataStructure) UnmarshalJSON

func (sds *ScenarioDataStructure) UnmarshalJSON(data []byte) error

type ScenarioSet

type ScenarioSet struct {
	// Reference to the TestCase this ScenarioSet belongs to
	TestCase *TestCase

	// Core data fields
	// todo LATER expand to support scenario definitions like `map[string]bool` without a struct template (probably by making changes to `DetectScenarioDataStructure`)
	ScenarioType types.Type // the data type that individual scenarios are based on, which may be an alias or pointer to another type containing the actual fields

	DataStructure ScenarioDataStructure // describes the type of data structure used to store scenarios
	Scenarios     []dst.Expr            // the individual scenarios themselves //todo LATER convert to type `[]Scenario`

	Runner dst.Stmt // the actual code that runs the subtest (which is expected to be either a `ForStmt` or a `RangeStmt`)

	// Derived analysis results
	NameField         string   // the name of the field representing each scenario's name, or "map key" if the map key is used as the name
	ExpectedFields    []string // the names of fields representing the expected results of each scenario
	HasFunctionFields bool     // whether the scenario type has any fields whose type is a function
	UsesSubtest       bool     // whether the test calls `t.Run()` inside the loop body
}

Represents the properties of a table-driven test by storing information about the scenarios and their structure, as well as various analysis results derived from this information.

func IdentifyScenarioSet

func IdentifyScenarioSet(tc *TestCase, statements []*ExpandedStatement) *ScenarioSet

Attempts to extract the table-driven properties of a test case using information extracted from its parsed statements

func (*ScenarioSet) Analyze

func (ss *ScenarioSet) Analyze()

Perform additional analysis based on the core data fields, populating the corresponding fields

func (*ScenarioSet) GetFields

func (ss *ScenarioSet) GetFields() iter.Seq[*types.Var]

Returns the fields of the struct type used to define scenarios, if possible. Note that fields defined like `a, b int` are treated as one `Field` element with multiple Names.

func (*ScenarioSet) GetRunnerStatements

func (ss *ScenarioSet) GetRunnerStatements() []dst.Stmt

Returns the statements that make up the loop body

func (*ScenarioSet) IdentifyScenarios

func (ss *ScenarioSet) IdentifyScenarios(expr dst.Expr, tc *TestCase) bool

Checks whether an expression has the same original (not underlying) type as the ScenarioType, and if so, saves the scenarios from the expression. Returns whether the scenarios were saved successfully. Always returns `false` if the `ScenarioSet.DataStructure` is unknown. See https://go.dev/ref/spec#Type_identity for details of the `types.Identical` comparison method.

func (*ScenarioSet) IsScenarioFromSamePackage added in v1.2.2

func (ss *ScenarioSet) IsScenarioFromSamePackage() bool

Returns whether the scenario type is defined in the same package as the test function

func (*ScenarioSet) IsTableDriven

func (ss *ScenarioSet) IsTableDriven() bool

Returns whether the detected information in the ScenarioSet is indicative of a table-driven test

func (*ScenarioSet) MarshalJSON

func (ss *ScenarioSet) MarshalJSON() ([]byte, error)

Marshal the ScenarioSet for JSON output

type TestCase

type TestCase struct {
	// High-level identifiers
	TestName    string // the name of the test case itself
	PackageName string // the name of the package where the test case is defined, as it appears in the source code
	FilePath    string // the path to the file where the test case is defined
	ProjectName string // the name of the overarching project that the test case is part of
	// contains filtered or unexported fields
}

Represents an individual test case defined at the top level of a Go source file.

func CreateTestCase

func CreateTestCase(funcDecl *dst.FuncDecl, file *dst.File, pkg *decorator.Package, project string) TestCase

Create a new TestCase struct for storage and analysis todo return error value more clearly either by returning nil or an error type

func (*TestCase) AstToDst added in v1.2.2

func (tc *TestCase) AstToDst(astNode ast.Node) dst.Node

Map an AST node to its corresponding DST (decorated) node to access better comment functionality.

func (*TestCase) DstStartPos added in v1.2.2

func (tc *TestCase) DstStartPos(dstNode dst.Node) token.Pos

Obtain the start position of a DST node by mapping it to its corresponding AST node. Equivalent to `tc.DstToAst(dstNode).Pos()`.

func (*TestCase) DstToAst added in v1.2.2

func (tc *TestCase) DstToAst(dstNode dst.Node) ast.Node

Map a DST node to its corresponding AST node to access type information.

func (*TestCase) Execute

func (tc *TestCase) Execute() (TestExecutionResult, error)

Execute a test based on the contents of its corresponding file in the file system using `go test`, and return the results. Returns an error if the test fails for any reason.

func (*TestCase) FileSet

func (tc *TestCase) FileSet() *token.FileSet

Get the the FileSet used for parsing the test's entire project

func (*TestCase) FunctionScope added in v1.2.2

func (tc *TestCase) FunctionScope() *types.Scope

Convenience method for getting the Scope corresponding to the TestCase's function. Returns `nil` if the type information for the project is not available.

func (*TestCase) GetFile

func (tc *TestCase) GetFile() *dst.File

Get the DST file where the test case is defined

func (*TestCase) GetFuncDecl

func (tc *TestCase) GetFuncDecl() *dst.FuncDecl

Get the DST function declaration for the test case

func (*TestCase) GetIdentDefinition added in v1.2.2

func (tc *TestCase) GetIdentDefinition(ident *dst.Ident) (token.Pos, *types.Package, bool, error)

Returns the position and package of the definition corresponding to the given identifier, and whether the package matches the current test case's package.

func (*TestCase) GetImportPath

func (tc *TestCase) GetImportPath() string

Get the entire import path of the test case's package, as used when importing the package, e.g. "github.com/user/repo/pkg/config"

func (*TestCase) GetImportPathRoot

func (tc *TestCase) GetImportPathRoot() string

Get the "repository root path" part of the test case's package import path. This is the part of the import path before the third slash, e.g. "github.com/user/repo" Note: this is somewhat brittle, and might not work well for all package paths.

func (*TestCase) GetJSONFilePath

func (tc *TestCase) GetJSONFilePath(dir string) string

Return the filepath where the test case's JSON representation should be saved, using the specified directory as a base if provided. The returned path is formatted like `<project>/<project>_<package>_<testName>.json`.

func (*TestCase) GetPackageFiles

func (tc *TestCase) GetPackageFiles() []*ast.File

Get all the AST files involved in the test case's package

func (*TestCase) GetPackageInfo

func (tc *TestCase) GetPackageInfo() *decorator.Package

Get the container for all raw information about the test case's package

func (*TestCase) GetStatements

func (tc *TestCase) GetStatements() []dst.Stmt

Return the list of statements in this test case

func (*TestCase) MarshalJSON

func (tc *TestCase) MarshalJSON() ([]byte, error)

Marshal a TestCase for JSON output

func (*TestCase) NumLines

func (tc *TestCase) NumLines() int

Return the number of individual lines (not statements) that the test case spans, or 0 if the number of lines cannot be determined.

func (*TestCase) NumStatements

func (tc *TestCase) NumStatements() int

Return the number of statements in the test case

func (*TestCase) ObjectOf

func (tc *TestCase) ObjectOf(ident *dst.Ident) types.Object

Convenience method for getting the Object corresponding to an identifier within the current TestCase's project. Returns `nil` if the type information for the project is not available, or if the identifier is not found.

func (*TestCase) String

func (tc *TestCase) String() string

Return a string representation of the TestCase for logging and debugging purposes

func (*TestCase) TypeInfo

func (tc *TestCase) TypeInfo() *types.Info

Get the type information for the test case's package

func (*TestCase) TypeOf

func (tc *TestCase) TypeOf(expr dst.Expr) types.Type

Convenience method for getting the type of an expression (including identifiers) within the current TestCase's project. Returns `nil` if the type information for the project is not available, or if the expression is not found.

func (*TestCase) UnmarshalJSON

func (tc *TestCase) UnmarshalJSON(data []byte) error

Unmarshal a TestCase from JSON

type TestExecutionResult

type TestExecutionResult int

Represents the result of a test execution, as run by the `go test` command.

const (
	TestExecutionResultNotRun           TestExecutionResult = iota // The test was not executed
	TestExecutionResultUnknown                                     // The test result could not be determined
	TestExecutionResultCompilationError                            // The test failed to compile
	TestExecutionResultSkip                                        // The test was skipped
	TestExecutionResultFail                                        // The test failed
	TestExecutionResultPass                                        // The test passed successfully
)

func (TestExecutionResult) MarshalJSON

func (ter TestExecutionResult) MarshalJSON() ([]byte, error)

func (TestExecutionResult) String

func (ter TestExecutionResult) String() string

func (*TestExecutionResult) UnmarshalJSON

func (ter *TestExecutionResult) UnmarshalJSON(data []byte) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址