Dev 1050 (ThinkR-open#1083)

* add user supplied `file` for `run_dev()` & make covr. 100% for `run_dev.R`  (ThinkR-open#1050)

* fix: user supplied 'file'-argument works correctly

- use path constructed from 'file' argument instead of hard code "dev/run_dev.R"
- improve error message on failure

Refs: ThinkR-open#886

* tests: improve test-covr. of run_dev.R form 0% to 100%

- add test for default 'file' argument
- add test for user supplied 'file' argument where
    - run_dev.R renamed to run_dev2.R
    - path to run_dev changed to top-level golem path
- add test for error if run_dev cannot find the 'file'

* docs: update docs for run_dev

- give a bit more context on usage
- fix some typos
- use markdown highlighting consistently
- add invisible return as this is a pure side-effect function

* core update README

---------

Co-authored-by: Ilya Zarubin <[email protected]>

R/run_dev.R

@@ -1,12 +1,25 @@
-#' Run run_dev.R
+#' Run the `dev/run_dev.R` file
 #'
-#' @param file File path to `run_dev.R`. Defaults to `R/run_dev.R`.
-#' @param save_all boolean. If TRUE, save all open file before sourcing `file`
+#' The default `file="dev/run_dev.R"` launches your `{golem}` app with a bunch
+#' of useful options. The file content can be customized and `file`-name and
+#' path changed as long as the argument combination of `file` and `pkg` are
+#' supplied correctly: the `file`-path is a relative path to a `{golem}`-package
+#' root `pkg`. An error is thrown if `pkg/file` cannot be found.
+#'
+#' The function `run_dev()` is typically used to launch a shiny app by sourcing
+#' the content of an appropriate `run_dev`-file. Carefully read the content of
+#' `dev/run_dev.R` when creating your custom `run_dev`-file. It has already
+#' many useful settings including a switch between production/development,
+#' reloading the package in a clean `R` environment before running the app etc.
+#'
+#' @param file String with (relative) file path to a `run_dev.R`-file
+#' @param save_all Boolean; if `TRUE` saves all open files before sourcing
+#'     `file`
 #' @inheritParams add_module
 #'
 #' @export
 #'
-#' @return Used for side-effect
+#' @return pure side-effect function; returns invisibly
 run_dev <- function(
   file = "dev/run_dev.R",
   pkg = get_golem_wd(),
@@ -31,12 +44,10 @@ run_dev <- function(
 
   # Stop if it doesn't exists
   if (file.exists(try_dev)) {
-    run_dev_lines <- readLines(
-      "dev/run_dev.R"
-    )
+    run_dev_lines <- readLines(try_dev)
   } else {
     stop(
-      "Unable to locate dev file"
+      "Unable to locate the run_dev-file passed via the 'file' argument."
     )
   }
 
@@ -45,4 +56,5 @@ run_dev <- function(
       text = run_dev_lines
     )
   )
+  return(invisible(file))
 }

README.md

@@ -112,28 +112,28 @@ This `README` has been compiled on the
 
 ``` r
 Sys.time()
-#> [1] "2023-08-08 18:26:15 UTC"
+#> [1] "2023-08-08 19:05:09 UTC"
 ```
 
 Here are the test & coverage results:
 
 ``` r
 devtools::check(quiet = TRUE)
 #> ℹ Loading golem
+#> Writing 'run_dev.Rd'
 #> ── R CMD check results ─────────────────────────────────────── golem 0.4.12 ────
-#> Duration: 2m 36.2s
+#> Duration: 2m 35.9s
 #> 
 #> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔
 ```
 
 ``` r
 covr::package_coverage()
-#> golem Coverage: 84.32%
+#> golem Coverage: 84.93%
 #> R/addins.R: 0.00%
 #> R/bootstrap_rstudio_api.R: 0.00%
 #> R/enable_roxygenize.R: 0.00%
 #> R/get_sysreqs.R: 0.00%
-#> R/run_dev.R: 0.00%
 #> R/sanity_check.R: 0.00%
 #> R/test_helpers.R: 30.26%
 #> R/js.R: 43.75%
@@ -157,6 +157,7 @@ covr::package_coverage()
 #> R/add_files.R: 92.31%
 #> R/golem-yaml-get.R: 93.18%
 #> R/add_dockerfiles_renv.R: 93.78%
+#> R/run_dev.R: 95.00%
 #> R/desc.R: 96.67%
 #> R/use_favicon.R: 96.67%
 #> R/use_readme.R: 97.14%

tests/testthat/test-run_dev.R

@@ -0,0 +1,47 @@
+path_dummy_golem <- tempfile(pattern = "dummygolem")
+create_golem(
+  path = path_dummy_golem,
+  open = FALSE
+)
+test_that("run_dev() works for different files and fails if missing", {
+  with_dir(
+    path_dummy_golem,
+    {
+      # Adjust file for testing run_dev() with default file="dev/run_dev.R"
+      run_dev_update <- readLines("dev/run_dev.R")
+      # suppress other behavior of run_dev that is not meant for testing
+      run_dev_update[2] <- "# options(golem.app.prod = FALSE)"
+      run_dev_update[6] <- "# options(shiny.port = httpuv::randomPort())"
+      run_dev_update[8] <- "# golem::detach_all_attached()"
+      run_dev_update[12] <- "# golem::document_and_reload()"
+      run_dev_update[15] <- "print('DEFAULT run_dev')"
+      # write new run_dev.R file for testing
+      run_dev_update <- writeLines(run_dev_update, "dev/run_dev.R")
+      # Make a copy of run_dev and move it elsewhere (but inside golem)
+      file.copy(
+        from = "dev/run_dev.R",
+        to = file.path(get_golem_wd(), "run_dev2.R")
+      )
+      # Adjust copy for testing run_dev() with user supplied file="run_dev2.R"
+      run_dev_update <- readLines("run_dev2.R")
+      run_dev_update[15] <- "print('NEW run_dev2')"
+      run_dev_update <- writeLines(run_dev_update, "run_dev2.R")
+      # The default run_dev works
+      expect_output(
+        run_dev(),
+        regexp = "DEFAULT run_dev"
+      )
+      # The new run_dev2 works too
+      expect_output(
+        run_dev(file = "run_dev2.R"),
+        regexp = "NEW run_dev2"
+      )
+      # A wrong path supplied to 'file' fails  with informative error
+      expect_error(
+        run_dev(file = "run_dev3.R"),
+        regexp = "Unable to locate the run_dev-file passed via the 'file' argument."
+      )
+      unlink(path_dummy_golem, recursive = TRUE)
+    }
+  )
+})