Package 'covtracer'

Description

Create an S3 list of srcref objects

Usage

as_list_of_srcref(x)

## S3 method for class 'environment'
as_list_of_srcref(x)

## S3 method for class 'list'
as_list_of_srcref(x)

Arguments

Value

A list_of_srcref class object

Description

Wrap object in test description derivation data

Adds "testthat" style

Usage

as_test_desc(x, type = "call")

as_testthat_desc(x)

Arguments

Value

A test_description subclass object with additional style attribute indicating how the test description was derived.

Description

Coerce a list_of_srcref object to a data.frame

Usage

## S3 method for class 'list_of_srcref'
as.data.frame(
  x,
  ...,
  use.names = TRUE,
  expand.srcref = FALSE,
  row.names = NULL
)

Arguments

Value

A data.frame with one record per srcref and variables:

name

Names of the srcref objects, passed using the names of x if use.names = TRUE

srcref

srcref objects if expand.srcrefs = FALSE

srcfile, line1, byte1, line2, col1, col2, parsed1, parsed2

The srcref file location if it can be determined. If an absolute path can't be found, only the base file name provided in the srcref object and the numeric components of the srcref objects if expand.srcrefs = TRUE

Examples

pkg <- system.file("examplepkg", package = "covtracer")
install.packages(
  pkg,
  type = "source",
  repos = NULL,
  quiet = TRUE,
  INSTALL_opts = "--with-keep.source"
)
as.data.frame(pkg_srcrefs("examplepkg"))

Description

Functionally identical to devtools' as.package, but without interactive options for package creation.

Usage

as.package(x)

Arguments

Value

A package object

Note

Code inspired by devtools load_pkg_description with very minor edits to further reduce devtools dependencies.

Description

Check whether the coverage object has expected fields produced when coverage was captured with option(covr.record_tests = TRUE), throwing an error if it was not.

Usage

coverage_check_has_recorded_tests(coverage, warn = TRUE)

Arguments

Value

Used for side-effects of emitting an error when a coverage object does not contain recorded traces, or a warning when a coverage object appears to have no tests.

See Also

Other coverage_tests: coverage_get_tests(), coverage_has_recorded_tests()

Description

Assumes the coverage object was produced while option(covr.record_tests = TRUE).

Usage

coverage_get_tests(coverage)

Arguments

Value

A list of tests evaluated when using covr

See Also

Other coverage_tests: coverage_check_has_recorded_tests(), coverage_has_recorded_tests()

Description

Test whether the coverage object has expected fields produced when coverage was captured with option(covr.record_tests = TRUE).

Usage

coverage_has_recorded_tests(coverage)

Arguments

Value

A logical value, indicating whether the coverage object has recorded tests, or NA when it does not appear to have traced any test code.

See Also

Other coverage_tests: coverage_check_has_recorded_tests(), coverage_get_tests()

Description

Convert an expression, call or symbol to a single-line string

Usage

expr_str(ref)

Arguments

Value

The given expression, formatted as a string with prefixes for symbols and generics.

Description

Map srcrefs over an iterable object, Filtering non-srcref results

Usage

flat_map_srcrefs(xs, ns = NULL, breadcrumbs = character())

Arguments

Value

A list of srcrefs

Description

Format list_of_srcref as character

Usage

## S3 method for class 'list_of_srcref'
format(x, ..., full.names = FALSE, full.num = FALSE)

Arguments

Value

A character vector of formatted strings

Description

Get namespace exports, filtering methods tables and definitions

Usage

get_namespace_object_names(ns)

Arguments

Value

The names of exported objects, filtering internal method tables and metadata.

Description

Get the full path to the srcref file

Usage

getSrcFilepath(x)

Arguments

Value

A character vector of source file paths.

Description

Test whether an object is a srcref object

Usage

is_srcref(x)

Arguments

Value

A logical indicating whether object is a srcref

Description

References to source code are defined by the source code line and column span of the relevant source code. This function takes data frames containing that information to pair source code in one data frame to source code from another. In this case, source code from the left hand data frame is paired if it is entirely contained within a record of source code in the right hand data frame.

Usage

join_on_containing_srcrefs(x, y, by = c(srcref = "srcref"))

Arguments

Value

A data.frame of x joined on y by spanning srcref

Description

Provided two lists of srcref objects, find the first srcrefs in r that entirely encapsulate each respective srcref in l, returning a list of indices of srcrefs in r for each srcref in l.

Usage

match_containing_srcrefs(l, r)

Arguments

Value

A integer vector of the first index in r that fully encapsulate the respective element in l

Description

Build an empty covr-style test trace mapping

Usage

new_empty_test_trace_tally()

Value

An empty test-trace matrix, as provided by covr

Description

For most objects, this will be identical to the namespace name provided, but reexports will retain their originating package's namespace name. This helper function helps to expose this name to determine which exports are reexports.

Usage

obj_namespace_name(x, ns)

Arguments

Value

A character string representing a namespace or similar

Description

Test whether the package object collection contains srcref attributes.

Usage

package_check_has_keep_source(env)

Arguments

Value

Used for side effect of throwing an error when a package was not installed with srcrefs.

Description

Extract all the srcref objects of objects within a package namespace

Usage

pkg_srcrefs(x)

## S3 method for class 'environment'
pkg_srcrefs(x)

## S3 method for class 'character'
pkg_srcrefs(x)

## S3 method for class 'coverage'
pkg_srcrefs(x)

Arguments

Value

A list_of_srcref

See Also

as.data.frame.list_of_srcref

Other srcrefs: test_srcrefs(), trace_srcrefs()

Examples

pkg <- system.file("examplepkg", package = "covtracer")
install.packages(
  pkg,
  type = "source",
  repos = NULL,
  quiet = TRUE,
  INSTALL_opts = "--with-keep.source"
)
pkg_srcrefs("examplepkg")

Description

Create a data.frame of package srcref objects

Usage

pkg_srcrefs_df(x)

Arguments

Value

A data.frame with a record for each source code block with variables:

name

A character Rd alias for the package object

srcref

The srcref of the associated package source code

See Also

srcrefs test_trace_mapping

Other srcrefs_df: test_srcrefs_df(), trace_srcrefs_df()

Examples

pkg <- system.file("examplepkg", package = "covtracer")
install.packages(
  pkg,
  type = "source",
  repos = NULL,
  quiet = TRUE,
  INSTALL_opts = "--with-keep.source"
)
pkg_srcrefs_df("examplepkg")

Description

Provides Rd index info with a few additional columns of information about each exported object. Returns one record per documented object, even if multiple objects alias to the same documentation file.

Usage

Rd_df(x)

Arguments

Value

A data.frame of documented object information with variables:

index

A numeric index of documentation files associated with documentation objects

file

A character filename of the Rd file in the "man" directory

filepath

A character file path of the Rd file in the "man" directory

alias

character object names which are aliases for the documentation in filepath

is_exported

A logical indicator of whether the aliased object is exported from the package namespace

doctype

A character representing the Rd docType field.

Examples

package_source_dir <- system.file("examplepkg", package = "covtracer")
Rd_df(package_source_dir)

Description

Parse the expression associated with a srcref

Usage

srcref_expr(ref)

Arguments

Value

A parsed srcref object

Description

Convert a srcref into a string

Usage

srcref_str(ref)

Arguments

Value

A string representing the srcref

Description

This function takes a code collection and returns a list of related srcref objects with list names that associate the srcref with a name or alias that could be used to find documentation. Code collections include structures such as package namespaces, environments, function definitions, methods tables or class generators - any object which enapsulates a single or set of srcref objects.

Usage

srcrefs(x, ...)

## Default S3 method:
srcrefs(x, ..., srcref_names = NULL, breadcrumbs = character())

## S3 method for class 'list'
srcrefs(x, ..., srcref_names = NULL, breadcrumbs = character())

## S3 method for class 'namespace'
srcrefs(x, ..., breadcrumbs = character())

## S3 method for class 'environment'
srcrefs(x, ..., breadcrumbs = character())

## S3 method for class 'R6ClassGenerator'
srcrefs(x, ..., srcref_names = NULL, breadcrumbs = character())

## S3 method for class 'standardGeneric'
srcrefs(x, ..., srcref_names = NULL)

## S3 method for class 'nonstandardGenericFunction'
srcrefs(x, ..., srcref_names = NULL)

## S3 method for class 'MethodDefinition'
srcrefs(x, ..., srcref_names = NULL)

Arguments

Details

For most objects, this is a one-to-one mapping of exported object names to their srcref, just like you would get using getNamespace(). However, for classes and methods, this can be a one-to-many mapping of related documentation to the multiple srcrefs that are described there. This is the case for S3 generics, S4 objects and R6 objects.

Objects without any related srcrefs, such as any datasets or objects created at package build time will be omitted from the results.

Value

A list of srcref objects. Often, has a length of 1, but can be larger for things like environments, namespaces or generic methods. The names of the list reflect the name of the Rd name or alias that could be used to find information related to each srcref. Elements of the list will have attribute "namespace" denoting the source environment namespace if one can be determined for the srcref object.

Examples

# examples use `with` to execute within namespace as function isn't exported
ns <- getNamespace("covtracer")

# load and extract srcrefs for a package
with(ns, srcrefs(getNamespace("covtracer")))

# extract srcrefs for functions
with(ns, srcrefs(srcrefs))

Description

In the general case, a simple indicator of the source file and line number is used as a test description. There are some special cases where more descriptive information can be extracted:

Usage

test_description(x)

Arguments

Details

testthat

If the test used test_that, then the description (desc parameter) is extracted and evaluated if need be to produce a descriptive string. Nested calls to test_that currently return the outermost test description, although this behavior is subject to change.

Value

A string that describes the test. If possible, this will be a written description of the test, but will fall back to the test call as a string in cases where no written description can be determined.

Description

Parse the test description from a test_that call

Usage

test_description_test_that(x, ...)

Arguments

Value

A character description, parsed from a test_that::test_that call

Description

Parse the test description from a describe call

Usage

test_description_test_that_describe(x, ...)

Arguments

Value

A character description, parsed from a test_that::describe call

Description

Parse the test description from a it call

Usage

test_description_test_that_describe_it(x, ...)

Arguments

Value

A character description, parsed from a test_that::it call

Description

Extract test srcref objects

Usage

test_srcrefs(x)

## S3 method for class 'coverage'
test_srcrefs(x)

Arguments

Value

A list_of_srcref

See Also

as.data.frame.list_of_srcref

Other srcrefs: pkg_srcrefs(), trace_srcrefs()

Examples

options(covr.record_tests = TRUE)
pkg_path <- system.file("examplepkg", package = "covtracer")
cov <- covr::package_coverage(pkg_path)
test_srcrefs(cov)

Description

Extract unit test srcrefs from a coverage object. A test name will be derived from the test source code, preferrably from a written annotation, but otherwise falling back to using a code snippet. srcrefs are unique for each expression executed within a testing suite.

Usage

test_srcrefs_df(x)

Arguments

Value

A data.frame of test srcrefs extracted from a coverage object. Contains one record for each srcref with variables:

name

A character test description. For testthat tests, the desc parameter will be used, otherwise a snippet of code will be used for the test name

srcref

A srcref object describing the location of the test

test_type

A character indicating the structure of the test. One of "testthat", "call" or NULL

See Also

srcrefs test_trace_mapping

Other srcrefs_df: pkg_srcrefs_df(), trace_srcrefs_df()

Examples

options(covr.record_tests = TRUE)
pkg_path <- system.file("examplepkg", package = "covtracer")
cov <- covr::package_coverage(pkg_path)
test_srcrefs_df(cov)

Description

Intercept unit test coverage reports and process results to link evaluated functions to the unit tests which trigger their evaluation. In doing so, we can then link the associated function documentation of each object to the tests that triggered their evaluation as a way of reusing existing documentation to generate specifications.

Usage

test_trace_df(x, ...)

## S3 method for class 'coverage'
test_trace_df(
  x,
  ...,
  pkg = as.package(attr(x, "package")$path),
  aggregate_by = sum
)

Arguments

Value

A data.frame of tests and corresponding traces

Description

Extract a matrix used to relate test code to the traces that each test evaluates.

Usage

test_trace_mapping(x)

Arguments

Value

A data.frame with one record for each line of code executed, with variables:

test

The index of the test that was executed, reflecting the order in which tests are executed

depth

The call stack depth when the coverage trace was evaluated

i

The index of the expression evaluated by each test. This can be used to recover an order of trace execution for a given test index

trace

The index of the coverage trace that was evaluated

See Also

srcrefs_df srcrefs

Examples

options(covr.record_tests = TRUE)
pkg_path <- system.file("examplepkg", package = "covtracer")
cov <- covr::package_coverage(pkg_path)
test_trace_mapping(cov)

Description

Extract srcref objects from coverage object traces

Usage

trace_srcrefs(x)

## S3 method for class 'coverage'
trace_srcrefs(x)

Arguments

Value

A list_of_srcref

See Also

as.data.frame.list_of_srcref

Other srcrefs: pkg_srcrefs(), test_srcrefs()

Description

Extract coverage traces. Traces are the traced lines of code counted when evaluating code coverage, which are used for counting expression evaluation. Each traced is a unique expression within a package's source code.

Usage

trace_srcrefs_df(x)

Arguments

Value

A data.frame, where each record it a trace srcref with variables:

name

A character identifier. This will use the names of the elements of a coverage object, which are srcref "keys".

srcref

A srcref object of the trace source code location

See Also

srcrefs test_trace_mapping

Other srcrefs_df: pkg_srcrefs_df(), test_srcrefs_df()

Examples

options(covr.record_tests = TRUE)
pkg_path <- system.file("examplepkg", package = "covtracer")
cov <- covr::package_coverage(pkg_path)
trace_srcrefs_df(cov)

Description

Most relevant data can be traced to an existing srcref. However, some data, such as test traces from coverage objects, are likely cleaned up and their srcfiles deleted, causing a barrage of warnings any time these objects are printed.

Usage

with_pseudo_srcref(call, file, lloc)

Arguments

Details

A pseudo_srcref adds in the srcref data but continues to preserve the expression content. This allows these expression objects to be pretty-printed like srcrefs when included as a list_of_srcref data.frame column.

Value

A with_pseudo_srcref object, mimicking the structure of srcref