Documentation
¶
Overview ¶
Package coverage is the statement-coverage extension of the runner: a collector the interpreter reports statement executions to, and the profile blocks a host renders from it.
Coverage is an interpreter feature. flatstack is a performance-oriented backend and carries no coverage support; a runner holding a collector executes interpreted (see runner.Runtime.SetCoverage).
Index ¶
- Constants
- func Name(filename string) string
- func Percent(blocks []ProfileBlock) float64
- func SortProfile(blocks []ProfileBlock)
- func SortRows(rows []Row)
- func WriteProfile(w io.Writer, blocks []ProfileBlock) error
- func WriteReport(w io.Writer, rows []Row) error
- type Aggregator
- type Block
- type Collector
- type FuncSpan
- type ProfileBlock
- type Row
Constants ¶
const ( ModeLine = "line" ModeFunc = "func" ModeFile = "file" )
The --cover modes. Line is what a bare --cover means: measure, write the profile, print the one-line percentage. Func and file also write the profile, then print a per-symbol report in the format go tool cover -func prints.
const DefaultCoverFile = "phpscript.cov"
DefaultCoverFile is where --cover writes the profile when --coverfile does not name one.
Variables ¶
This section is empty.
Functions ¶
func Name ¶ added in v0.5.0
Name is how a file is spelled in a profile: below the directory the command ran in, with no leading separator.
The interpreter anchors an entrypoint at the source filesystem root for __FILE__ ("/app.php") and names an include as it resolved it ("app.php"). Both are the same file, and a report that kept the two spellings apart would count it twice.
func Percent ¶ added in v0.5.0
func Percent(blocks []ProfileBlock) float64
Percent is the statement-weighted percentage go test reports: statements in blocks that ran, over all registered statements.
func SortProfile ¶ added in v0.5.0
func SortProfile(blocks []ProfileBlock)
SortProfile orders blocks by file and position, which is the order a profile is written in.
func SortRows ¶ added in v0.5.0
func SortRows(rows []Row)
SortRows orders report rows by file, then position, then symbol.
func WriteProfile ¶ added in v0.5.0
func WriteProfile(w io.Writer, blocks []ProfileBlock) error
WriteProfile writes blocks in the format go test -coverprofile writes, with the measurement mode go names "count".
Types ¶
type Aggregator ¶ added in v0.5.0
type Aggregator struct {
// contains filtered or unexported fields
}
Aggregator accumulates the counts of many collectors for the lifetime of a process. Counts add: a statement two requests reached ran twice.
A Collector keys statements by AST node, so one kept across requests grows with every re-parse. The aggregator keys them by the profile line they will be written as, which is bounded by the size of the application.
func NewAggregator ¶ added in v0.5.0
func NewAggregator() *Aggregator
NewAggregator returns an empty aggregator.
func (*Aggregator) Add ¶ added in v0.5.0
func (a *Aggregator) Add(c *Collector)
Add folds one collector's counts in and returns. The collector is read, not retained, so the caller may drop it and the AST it keys on.
func (*Aggregator) Blocks ¶ added in v0.5.0
func (a *Aggregator) Blocks() []Block
Blocks returns the accumulated counts as profile entries, sorted by file and position.
func (*Aggregator) Empty ¶ added in v0.5.0
func (a *Aggregator) Empty() bool
Empty reports whether anything has been folded in yet. A server that served no PHP writes no profile rather than an empty one.
func (*Aggregator) Files ¶ added in v0.5.0
func (a *Aggregator) Files() []string
Files returns every registered filename, sorted.
func (*Aggregator) Functions ¶ added in v0.5.0
func (a *Aggregator) Functions() []FuncSpan
Functions returns the declaration spans seen, sorted by file and position.
type Block ¶
Block is one line-range entry of a coverage profile. Lines only: the parser records no columns, so a profile writer chooses them (the test command derives them from the source text).
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
Collector accumulates statement execution counts, keyed by the statement nodes the parser produced.
A program is registered before it runs, seeding every executable statement at count zero under the filename it was loaded from. The entrypoint and every include register, so the files in a profile are the files get_included_files reports, and an included-but-unexecuted statement still appears, at zero.
func (*Collector) Blocks ¶
Blocks renders the collected counts as profile entries, sorted by file and position. Statements sharing a line range merge into one block: NumStmt adds up, and Count is the largest of theirs, which is how many times the line was reached — summing would charge `$a = 1; $b = 2;` twice per pass.
func (*Collector) Files ¶
Files returns every registered filename, sorted. A file appears whether or not it holds an executable statement: a file of pure declarations registers no counts, and a report that renders only counted blocks would omit it, reading as a gap where there is nothing to run.
func (*Collector) Functions ¶
Functions returns the registered declaration spans, sorted by file and position. Every function of every registered file appears, called or not: an uncalled function is the zero row a per-function report exists to show.
func (*Collector) Hit ¶
Hit charges one execution to a registered statement. An unregistered statement (a declaration, or a program built without the parser) is not counted.
func (*Collector) Register ¶
Register seeds every executable statement of program at count zero under filename. Declarations are not executable and are skipped; their bodies' statements carry spans of their own. A statement already registered keeps its count, so re-including a cached program does not reset it.
type FuncSpan ¶
FuncSpan is the source range of one declared function: a free function under its name, a method under Class::name. A per-function report charges the blocks inside the range to it.
type ProfileBlock ¶ added in v0.5.0
type ProfileBlock struct {
File string
StartLine int
StartCol int
EndLine int
EndCol int
NumStmt int
Count int
}
ProfileBlock is one line of a written profile: a coverage block with its columns resolved from the source text. The collector reports lines only; the columns exist so the profile is the format go test writes and go tool cover renders, spanning the statement text rather than the indentation around it.
func Columns ¶ added in v0.5.0
func Columns(blocks []Block, source func(file string) []string) []ProfileBlock
Columns resolves each block's columns against the source text of the file it came from. source returns the lines of a file, or nil when the host cannot read it, in which case the block keeps column 1 on both ends.
type Row ¶ added in v0.5.0
Row is one line of a func or file report: the location column go tool cover -func prints, the symbol charged, and the statements counted against it.
func FileRows ¶ added in v0.5.0
func FileRows(blocks []ProfileBlock, files []string) []Row
FileRows reports one row per registered source file. A file with no runnable statement stays in the report at its adjusted percentage.
func FuncRows ¶ added in v0.5.0
func FuncRows(blocks []ProfileBlock, funcs []FuncSpan, files []string) []Row
FuncRows charges each profile block to the innermost declaration span containing its start line. A block inside no declaration is the file's top-level code, reported as {main} - the name PHP gives that scope - at the first such line. files names every registered file, so one holding nothing runnable still reports a row.
Source Files