Documentation
¶
Index ¶
- func IsValidTestCase(funcDecl *dst.FuncDecl) (valid bool, badFormat bool)
- type AnalysisResult
- func (ar *AnalysisResult) AttemptRefactoring(strategy RefactorStrategy, keepRefactoredFiles bool) RefactorResult
- func (ar *AnalysisResult) EncodeAsCSV() []string
- func (ar *AnalysisResult) GetCSVHeaders() []string
- func (ar *AnalysisResult) IsTableDriven() bool
- func (ar *AnalysisResult) SaveAsJSON(dir string) error
- type ExpandedStatement
- type ExpressionDefinition
- type RefactorGenerationStatus
- type RefactorResult
- type RefactorStrategy
- type RefactoredFunction
- type Scenario
- type ScenarioDataStructure
- type ScenarioSet
- func (ss *ScenarioSet) Analyze()
- func (ss *ScenarioSet) GetFields() iter.Seq[*types.Var]
- func (ss *ScenarioSet) GetRunnerStatements() []dst.Stmt
- func (ss *ScenarioSet) IdentifyScenarios(expr dst.Expr, tc *TestCase) bool
- func (ss *ScenarioSet) IsScenarioFromSamePackage() bool
- func (ss *ScenarioSet) IsTableDriven() bool
- func (ss *ScenarioSet) MarshalJSON() ([]byte, error)
- type TestCase
- func (tc *TestCase) AstToDst(astNode ast.Node) dst.Node
- func (tc *TestCase) DstStartPos(dstNode dst.Node) token.Pos
- func (tc *TestCase) DstToAst(dstNode dst.Node) ast.Node
- func (tc *TestCase) Execute() (TestExecutionResult, error)
- func (tc *TestCase) FileSet() *token.FileSet
- func (tc *TestCase) FunctionScope() *types.Scope
- func (tc *TestCase) GetFile() *dst.File
- func (tc *TestCase) GetFuncDecl() *dst.FuncDecl
- func (tc *TestCase) GetIdentDefinition(ident *dst.Ident) (token.Pos, *types.Package, bool, error)
- func (tc *TestCase) GetImportPath() string
- func (tc *TestCase) GetImportPathRoot() string
- func (tc *TestCase) GetJSONFilePath(dir string) string
- func (tc *TestCase) GetPackageFiles() []*ast.File
- func (tc *TestCase) GetPackageInfo() *decorator.Package
- func (tc *TestCase) GetStatements() []dst.Stmt
- func (tc *TestCase) MarshalJSON() ([]byte, error)
- func (tc *TestCase) NumLines() int
- func (tc *TestCase) NumStatements() int
- func (tc *TestCase) ObjectOf(ident *dst.Ident) types.Object
- func (tc *TestCase) String() string
- func (tc *TestCase) TypeInfo() *types.Info
- func (tc *TestCase) TypeOf(expr dst.Expr) types.Type
- func (tc *TestCase) UnmarshalJSON(data []byte) error
- type TestExecutionResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsValidTestCase ¶
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 ¶
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
Map an AST node to its corresponding DST (decorated) node to access better comment functionality.
func (*TestCase) DstStartPos ¶ added in v1.2.2
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
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) FunctionScope ¶ added in v1.2.2
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) GetFuncDecl ¶
Get the DST function declaration for the test case
func (*TestCase) GetIdentDefinition ¶ added in v1.2.2
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 ¶
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 ¶
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 ¶
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 ¶
Get all the AST files involved in the test case's package
func (*TestCase) GetPackageInfo ¶
Get the container for all raw information about the test case's package
func (*TestCase) GetStatements ¶
Return the list of statements in this test case
func (*TestCase) MarshalJSON ¶
Marshal a TestCase for JSON output
func (*TestCase) NumLines ¶
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 ¶
Return the number of statements in the test case
func (*TestCase) ObjectOf ¶
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 ¶
Return a string representation of the TestCase for logging and debugging purposes
func (*TestCase) TypeOf ¶
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 ¶
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