Documentation
¶
Index ¶
- Constants
- Variables
- func GetUniquePCsCount(compilations []types.Compilation, coverageMaps *CoverageMaps, ...) (int, error)
- func RemoveCoverageTracerResults(messageResults *types.MessageResults)
- func WriteHTMLReport(sourceAnalysis *SourceAnalysis, reportDir string) (string, error)
- func WriteLCOVReport(sourceAnalysis *SourceAnalysis, reportDir string) (string, error)
- type ContractCoverageMap
- type CoverageMaps
- func (cm *CoverageMaps) BranchesHit() uint64
- func (cm *CoverageMaps) Equal(b *CoverageMaps) bool
- func (cm *CoverageMaps) GetContractCoverageMap(bytecode []byte, init bool) (*ContractCoverageMap, error)
- func (cm *CoverageMaps) Reset()
- func (cm *CoverageMaps) Update(coverageMaps *CoverageMaps) (bool, error)
- func (cm *CoverageMaps) UpdateAt(codeAddress common.Address, codeLookupHash common.Hash, marker uint64) (bool, error)
- type CoverageTracer
- func (t *CoverageTracer) CaptureTxEndSetAdditionalResults(results *types.MessageResults)
- func (t *CoverageTracer) NativeTracer() *chain.TestChainTracer
- func (t *CoverageTracer) OnEnter(depth int, typ byte, from common.Address, to common.Address, input []byte, ...)
- func (t *CoverageTracer) OnExit(depth int, output []byte, gasUsed uint64, err error, reverted bool)
- func (t *CoverageTracer) OnOpcode(pc uint64, op byte, gas, cost uint64, scope tracing.OpContext, rData []byte, ...)
- func (t *CoverageTracer) OnTxStart(vm *tracing.VMContext, tx *coretypes.Transaction, from common.Address)
- func (t *CoverageTracer) SetInitialContractsSet(initialContractsSet *map[common.Address]struct{})
- type SourceAnalysis
- type SourceFileAnalysis
- type SourceLineAnalysis
Constants ¶
const ( REVERT_MARKER_XOR = 0x40000000 RETURN_MARKER_XOR = 0x80000000 ENTER_MARKER_XOR = 0xC0000000 )
Constants used in markers. See comments on ContractCoverageMap.executedMarkers for more details on how these are used. These are high (> 1 billion) so that it should never overlap with real PCs, ie so that these markers should never overlap with jump markers.
Variables ¶
var BLANK_ADDRESS = common.BytesToAddress([]byte{})
BLANK_ADDRESS is an all-zero address; it's a global var so that we don't have to recalculate (and reallocate) it every time.
Functions ¶
func GetUniquePCsCount ¶ added in v1.2.0
func GetUniquePCsCount(compilations []types.Compilation, coverageMaps *CoverageMaps, logger *logging.Logger) (int, error)
GetUniquePCsCount returns the number of PCs in all contracts hit by our tests.
func RemoveCoverageTracerResults ¶
func RemoveCoverageTracerResults(messageResults *types.MessageResults)
RemoveCoverageTracerResults removes CoverageMaps stored by a CoverageTracer from message results.
func WriteHTMLReport ¶ added in v0.1.7
func WriteHTMLReport(sourceAnalysis *SourceAnalysis, reportDir string) (string, error)
WriteHTMLReport takes a previously performed source analysis and generates an HTML coverage report from it.
func WriteLCOVReport ¶ added in v0.1.7
func WriteLCOVReport(sourceAnalysis *SourceAnalysis, reportDir string) (string, error)
WriteLCOVReport takes a previously performed source analysis and generates an LCOV report from it.
Types ¶
type ContractCoverageMap ¶ added in v0.1.1
type ContractCoverageMap struct {
// contains filtered or unexported fields
}
ContractCoverageMap represents a data structure used to identify execution coverage of a contract.
func (*ContractCoverageMap) Equal ¶ added in v0.1.1
func (cm *ContractCoverageMap) Equal(b *ContractCoverageMap) bool
Equal checks whether the provided ContractCoverageMap contains the same data as the current one. Returns a boolean indicating whether the two maps match.
func (*ContractCoverageMap) HitCount ¶ added in v1.2.0
func (cm *ContractCoverageMap) HitCount(marker uint64) uint64
HitCount returns the number of times that the provided marker has been hit. If zero is returned, then the marker has not been hit or the map is nil
type CoverageMaps ¶
type CoverageMaps struct {
// contains filtered or unexported fields
}
CoverageMaps represents a data structure used to identify branch coverage of various smart contracts across a transaction or multiple transactions. Branch coverage includes jumps, returns, reverts, and contract entrance.
func GetCoverageTracerResults ¶
func GetCoverageTracerResults(messageResults *types.MessageResults) *CoverageMaps
GetCoverageTracerResults obtains CoverageMaps stored by a CoverageTracer from message results. This is nil if no CoverageMaps were recorded by a tracer (e.g. CoverageTracer was not attached during this message execution).
func NewCoverageMaps ¶
func NewCoverageMaps() *CoverageMaps
NewCoverageMaps initializes a new CoverageMaps object.
func (*CoverageMaps) BranchesHit ¶ added in v1.2.0
func (cm *CoverageMaps) BranchesHit() uint64
BranchesHit is a function that returns the total number of unique markers. Technically these markers can also refer to contract entrance, return, and revert, but calling it "branches" is close enough.
func (*CoverageMaps) Equal ¶ added in v0.1.1
func (cm *CoverageMaps) Equal(b *CoverageMaps) bool
Equal checks whether two coverage maps are the same. Equality is determined if the keys and values are all the same.
func (*CoverageMaps) GetContractCoverageMap ¶ added in v0.1.1
func (cm *CoverageMaps) GetContractCoverageMap(bytecode []byte, init bool) (*ContractCoverageMap, error)
GetContractCoverageMap obtains a total coverage map representing coverage for the provided bytecode. If the provided bytecode could not find coverage maps, nil is returned. Returns the total coverage map, or an error if one occurs.
func (*CoverageMaps) Reset ¶
func (cm *CoverageMaps) Reset()
Reset clears the coverage state for the CoverageMaps.
func (*CoverageMaps) Update ¶
func (cm *CoverageMaps) Update(coverageMaps *CoverageMaps) (bool, error)
Update updates the current coverage maps with the provided ones. Returns a boolean indicating whether coverage changed, or an error if one occurred.
type CoverageTracer ¶
type CoverageTracer struct {
// contains filtered or unexported fields
}
CoverageTracer implements tracers.Tracer to collect information such as coverage maps for fuzzing campaigns from EVM execution traces.
func NewCoverageTracer ¶
func NewCoverageTracer() *CoverageTracer
NewCoverageTracer returns a new CoverageTracer.
func (*CoverageTracer) CaptureTxEndSetAdditionalResults ¶
func (t *CoverageTracer) CaptureTxEndSetAdditionalResults(results *types.MessageResults)
CaptureTxEndSetAdditionalResults can be used to set additional results captured from execution tracing. If this tracer is used during transaction execution (block creation), the results can later be queried from the block. This method will only be called on the added tracer if it implements the extended TestChainTracer interface.
func (*CoverageTracer) NativeTracer ¶ added in v0.1.4
func (t *CoverageTracer) NativeTracer() *chain.TestChainTracer
NativeTracer returns the underlying TestChainTracer.
func (*CoverageTracer) OnEnter ¶ added in v0.1.4
func (t *CoverageTracer) OnEnter(depth int, typ byte, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int)
OnEnter initializes the tracing operation for the top of a call frame, as defined by tracers.Tracer.
func (*CoverageTracer) OnExit ¶ added in v0.1.4
OnExit is called after a call to finalize tracing completes for the top of a call frame, as defined by tracers.Tracer.
func (*CoverageTracer) OnOpcode ¶ added in v0.1.4
func (t *CoverageTracer) OnOpcode(pc uint64, op byte, gas, cost uint64, scope tracing.OpContext, rData []byte, depth int, err error)
OnOpcode records data from an EVM state update, as defined by tracers.Tracer.
func (*CoverageTracer) OnTxStart ¶ added in v0.1.4
func (t *CoverageTracer) OnTxStart(vm *tracing.VMContext, tx *coretypes.Transaction, from common.Address)
OnTxStart is called upon the start of transaction execution, as defined by tracers.Tracer.
func (*CoverageTracer) SetInitialContractsSet ¶ added in v1.3.0
func (t *CoverageTracer) SetInitialContractsSet(initialContractsSet *map[common.Address]struct{})
SetInitialContractsSet sets the initialContractsSet value (see above).
type SourceAnalysis ¶ added in v0.1.1
type SourceAnalysis struct {
// Files describes the analysis results for a given source file path.
Files map[string]*SourceFileAnalysis
}
SourceAnalysis describes source code coverage across a list of compilations, after analyzing associated CoverageMaps.
func AnalyzeSourceCoverage ¶ added in v0.1.1
func AnalyzeSourceCoverage(compilations []types.Compilation, coverageMaps *CoverageMaps, exclusionPatterns []string, logger *logging.Logger) (*SourceAnalysis, error)
AnalyzeSourceCoverage takes a list of compilations, coverage maps, and exclusion patterns, then performs source analysis to determine source coverage information. Files matching the exclusion patterns will be filtered out from the results. Returns a SourceAnalysis object, or an error if one occurs.
func (*SourceAnalysis) ActiveLineCount ¶ added in v0.1.1
func (s *SourceAnalysis) ActiveLineCount() int
ActiveLineCount returns the count of lines that are marked executable/active across all source files.
func (*SourceAnalysis) CoveredLineCount ¶ added in v0.1.1
func (s *SourceAnalysis) CoveredLineCount() int
CoveredLineCount returns the count of lines that were covered across all source files.
func (*SourceAnalysis) GenerateLCOVReport ¶ added in v0.1.7
func (s *SourceAnalysis) GenerateLCOVReport() string
GenerateLCOVReport generates an LCOV report from the source analysis. The spec of the format is here https://github.com/linux-test-project/lcov/blob/07a1127c2b4390abf4a516e9763fb28a956a9ce4/man/geninfo.1#L989
func (*SourceAnalysis) LineCount ¶ added in v0.1.1
func (s *SourceAnalysis) LineCount() int
LineCount returns the count of lines across all source files.
func (*SourceAnalysis) SortedFiles ¶ added in v0.1.1
func (s *SourceAnalysis) SortedFiles() []*SourceFileAnalysis
SortedFiles returns a list of Files within the SourceAnalysis, sorted by source file path in alphabetical order.
type SourceFileAnalysis ¶ added in v0.1.1
type SourceFileAnalysis struct {
// Path describes the file path of the source file. This is kept here for access during report generation.
Path string
// CumulativeOffsetByLine describes the cumulative byte offset for each line in the source file.
// For example, for a file with 5 lines, the list might look like: [0, 45, 98, 132, 189], where each number is the byte offset of the line's starting position
// This allows us to quickly determine which line a given byte offset falls within using a binary search.
CumulativeOffsetByLine []int
// Lines describes information about a given source line and its coverage.
Lines []*SourceLineAnalysis
// Functions is a list of functions defined in the source file
Functions []*types.FunctionDefinition
}
SourceFileAnalysis describes coverage information for a given source file.
func (*SourceFileAnalysis) ActiveLineCount ¶ added in v0.1.1
func (s *SourceFileAnalysis) ActiveLineCount() int
ActiveLineCount returns the count of lines that are marked executable/active within the source file.
func (*SourceFileAnalysis) CoveredLineCount ¶ added in v0.1.1
func (s *SourceFileAnalysis) CoveredLineCount() int
CoveredLineCount returns the count of lines that were covered within the source file.
type SourceLineAnalysis ¶ added in v0.1.1
type SourceLineAnalysis struct {
// IsActive indicates the given source line was executable.
IsActive bool
// Start describes the starting byte offset of the line in its parent source file.
Start int
// End describes the ending byte offset of the line in its parent source file.
End int
// Contents describe the bytes associated with the given source line.
Contents []byte
// IsCovered indicates whether the source line has been executed without reverting.
IsCovered bool
// SuccessHitCount describes how many times this line was executed successfully
SuccessHitCount uint64
// RevertHitCount describes how many times this line reverted during execution
RevertHitCount uint64
// IsCoveredReverted indicates whether the source line has been executed before reverting.
IsCoveredReverted bool
}
SourceLineAnalysis describes coverage information for a specific source file line.