In metrumresearchgroup/mrgvalidate: Create Validation Docs For R Packages

options(rmarkdown.html_vignette.check_title = FALSE)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  echo = TRUE,
  message = FALSE
)
library(knitr)
library(kableExtra)
library(dplyr)
library(tidyr)
# if (interactive()) {
#   devtools::load_all()
# }

Introduction

The purpose of the mrgvalidate package is to generate 7 specific documents that are necessary for the software validation process at Metrum Research Group. Those documents are:

• release-notes.docx
• validation-plan.docx
• testing-plan.docx
• requirements-specification.docx
• traceability-matrix.docx
• testing-results.docx
• validation-summary.docx

This vignette demonstrates how to generate these with a few simple library calls.

library(mrgvalidate)

Generating the docs

By default, these calls (create_package_docs() and create_metworx_docs()) will write .docx files for all seven documents into your working directory. Parameterized .Rmd files are first copied over, but are removed at the end (you can override this with the argument cleanup_rmd = FALSE). If all input data conforms to what is described in ?mrgvalidate::input_formats, you should only have to write a single a line.

The spec_df object and test directories below are created by helper functions in the mrgvalprep package. See the function documentation for more details.

Usage: Packages

create_package_docs(
  product_name = "Fake Product", 
  version = "vFake", 
  repo_url = "[e-mail]:metrumresearchgroup/mrgvalidate.git",
  specs = spec_df,                # a tibble containing stories and requirements to validate
  release_notes_file = "NEWS.md", # file path to a formatted markdown doc of release notes.
  auto_test_dir = "some_dir",     # directory containing automated test results
  style_dir = "style_ref_dir"     # Directory that has style references for the generated docx files
)

See ?create_package_docs for other arguments to tweak how and where the documents are rendered. The contents of the release_notes_file file should be filtered to just the current version via mrgvalprep.

Usage: Metworx Platform (experimental)

create_metworx_docs(
  product_name = "Fake Product", 
  version = "vFake", 
  specs = spec_df,                # a tibble containing stories and requirements to validate
  release_notes_file = "NEWS.md", # file path to a formatted markdown doc of release notes.
  auto_test_dir = "some_dir",     # directory containing automated test results
  man_test_dir = "some_dir",      # directory containing automated test results
  style_dir = "style_ref_dir",    # Directory that has style references for the generated docx files
  output_dir = "output_dir"
)

See ?create_metworx_docs for other arguments to tweak how and where the documents are rendered.

Example

If the documents produced by create_package_docs() or create_metworx_docs() don't look right, or you need to debug for any reason, you can run the pieces separately. For the demonstration below, we will use the following constants:

TEST_INPUTS_DIR <- system.file("test-inputs", package = "mrgvalidate")
output_dir <- file.path("mrgvalidate-create-validation-docs")
product_name <- "example"

# Filter to automatic tests only
specs <- readRDS(file.path(TEST_INPUTS_DIR, "specs.RDS")) %>% dplyr::filter(!grepl("MAN", TestIds))

if (fs::dir_exists(output_dir)) fs::dir_delete(output_dir)
fs::dir_create(output_dir)

res_df <- 
  mrgvalidate::create_package_docs(
  product_name = product_name,
  version = "vFAKE",
  repo_url = "[e-mail]:metrumresearchgroup/mrgvalidate.git",
  specs = specs,
  release_notes_file = file.path(TEST_INPUTS_DIR, "release_notes_sample.md"),
  auto_test_dir = file.path(TEST_INPUTS_DIR, "validation-results-sample"),
  output_dir = output_dir
)

list.files(output_dir)

Debugging

Packages do not have manual tests, but for demonstration purposes lets include the previously filtered out manual tests. By default, any missing required links will cause the docs to not be rendered. Additionally, a message displaying the missing links will be returned.

specs <- readRDS(file.path(TEST_INPUTS_DIR, "specs.RDS"))

res_df <- 
  mrgvalidate::create_package_docs(
  product_name = product_name,
  version = "vFAKE",
  repo_url = "[e-mail]:metrumresearchgroup/mrgvalidate.git",
  specs = specs,
  release_notes_file = file.path(TEST_INPUTS_DIR, "release_notes_sample.md"),
  auto_test_dir = file.path(TEST_INPUTS_DIR, "validation-results-sample"),
  output_dir = output_dir
)

You can also call find_missing() to return all missing links, though unlinked tests are entirely acceptable.

mrgvalidate::find_missing(res_df)

You can easily return the combined dataframe, without generating any of the validation docs, with join_specs_to_tests(), which can be useful for quick debugging:

res_df <- mrgvalidate::join_specs_to_tests(
  specs = specs,
  auto_test_dir = file.path(TEST_INPUTS_DIR, "validation-results-sample")
)

res_df %>% tidyr::unnest(tests)

res_df %>% tidyr::unnest(tests) %>% knitr::kable() %>% kable_styling("striped") %>% scroll_box(width = "100%")

fs::dir_delete(output_dir) 

metrumresearchgroup/mrgvalidate documentation built on March 4, 2023, 7:54 a.m.