% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/testit.R
\name{test_pkg}
\alias{test_pkg}
\title{Run all tests for a package}
\usage{
test_pkg(package = pkg_name(), dir = NULL, filter = NULL, update = NA)
}
\arguments{
\item{package}{The package name. By default, it is detected from the
\code{DESCRIPTION} file.}

\item{dir}{The directory containing test files. If \code{NULL} (the default),
\verb{testit/} or \verb{tests/testit/} under the current working directory is used
(whichever exists). You can also pass a custom path.}

\item{filter}{An optional regular expression to select a subset of test
files. Only files whose names match the pattern will be run. For example,
\code{filter = "plot"} runs only test files with "plot" in their names.}

\item{update}{Controls snapshot file behavior:
\itemize{
\item \code{TRUE}: always update snapshot files with actual output (never errors).
\item \code{NA} (default): update only if the file is tracked by Git (so you can
review diffs before accepting).
\item \code{FALSE}: never update; always compare and error on mismatch.
}}
}
\value{
Invisible \code{NULL}. If any tests fail, a single error is thrown at the
end with all failure messages combined.
}
\description{
Discover and execute test files (\verb{test-*.R} and \verb{test-*.md}) for a package.
Tests are run inside the package namespace, so you can call internal
(non-exported) functions directly without the \code{:::} operator.
}
\details{
Test files are looked up in the \verb{testit/} or \verb{tests/testit/} directory by
default. Files must be named \verb{test-*.R} for regular tests or \verb{test-*.md} for
snapshot tests. Other files in the directory are ignored (but you can
\code{\link[=source]{source()}} them from your tests if needed).

Helper files named \code{helper*.R} (e.g., \code{helper.R}, \code{helper-utils.R}) are
sourced before any test file runs. Objects defined in helpers are available
to all tests.

Each test file runs in a clean environment (previous test objects are
removed), and the working directory is set to the directory containing the
test file.

See \url{https://pkg.yihui.org/testit/#snapshot-testing} for more details about
snapshot testing.
}
\note{
You must call \code{library(testit)} before \code{test_pkg()}. Test scripts use
\code{\link[=assert]{assert()}} and other \strong{testit} functions without the \verb{testit::} prefix, so
the package needs to be on the search path. Without \code{library(testit)}, you
will get "could not find function" errors.

All test scripts must be encoded in UTF-8 if they contain multibyte
characters.

When \code{filter} or \code{update} are not explicitly provided, \code{test_pkg()} checks
\code{commandArgs(TRUE)} for command-line arguments: \code{--filter=PATTERN} sets the
filter, and \code{--update} sets \code{update = TRUE}. This allows you to pass these
options via \verb{Rscript tests/*.R --filter=PATTERN --update} without modifying
individual \code{test_pkg()} calls.
}
\examples{
\dontrun{
library(testit)
test_pkg('testit')
}
}
