#' Checks to run before initializing the shinyValidator template

#'

#' Useful for \link{use_validator}

#'

#' @inheritParams use_validator

#'

#' @return Error if any of the requirement is not met.

#' @keywords internal

check_setup_requirements <- function(cicd_platform) {

  }

  }

  }

  }

  }

  # Requires gh-pages branch if GitHub

  } else {

  }

}

#' Check if git is initialized locally

#'

#' @return Boolean.

#' @keywords internal

is_git_repository <- function() {

}

#' Check if current repo has remote part

#'

#' @return Boolean.

#' @keywords internal

has_git_remote <- function() {

}

#' Find a git branch

#'

#' @param name Branch name.

#'

#' @return Branch name if found

#' @keywords internal

find_branch <- function(name) {

  }

}

#' Find the main branch

#'

#' @return master or main depending on the initial configuration.

#' @keywords internal

find_main_branch <- function() {

}

#' Checks if gh_pages branch exists

#'

#' Creates gh_pages branch if not

#'

#' @inheritParams use_validator

#' @keywords internal

initialize_gh_pages <- function(cicd_platform) {

    }

      )

    )

        ),

      )

    } else {

    }

  }

}

#' Process scope for project

#'

#' @param scope Current project scope

#'

#' @return Reassign parms based on the scope

#' @keywords internal

process_scope <- function(scope) {

  )

}

#' Apply DMC scope

#'

#' DMC are the most critical applications

#'

#' @keywords internal

apply_dmc_scope <- function() { # nocov start

} # nocov end

#' Apply POC scope

#'

#' POC apps just need basic check: lint, style + crash test

#'

#' @keywords internal

apply_poc_scope <- function() {

  # need to modify env in grand parent

  # (apply_poc_scope -- process_scope -- use_validator)

}

#' Checks if the validator is already installed

#'

#' @inheritParams use_validator

#'

#' @return Boolean.

#' @keywords internal

check_if_validator_installed <- function(cicd_platform) {

  )

  } else {

  }

}

#' Copy and rename app helpers

#'

#' @keywords internal

copy_app_file <- function() {

  )

  # Comment out old files

  )

}

#' Edit .Rbuildignore file

#' @inheritParams use_validator

#' @return Edit existing .Rbuidignore file with additional entries

#' @keywords internal

edit_buildignore <- function(cicd_platform) {

  )

      # if audit_app is run locally

    )

  )

}

suggested_pkgs_names <- c(

  "DT",

  "testthat",

  "shinyValidator",

  "pkgload",

  "lubridate",

  "rmarkdown",

  "vdiffr",

  "withr"

)

shinyValidator_suggested_pkgs <- data.frame(

  name = suggested_pkgs_names,

  type = rep("Suggests", length(suggested_pkgs_names))

)

globalVariables("shinyValidator_suggested_pkgs")

#' Add suggested pkgs to DESCRIPTION

#'

#' These pkgs are required to perform the CICD job

#'

#' @return Edit the current Suggests DESCRIPTION fields

#' @keywords internal

add_suggested_packages <- function() {

      )

    }

  )

}

#' Add local copy of gremlins.js

#'

#' Useful if running behind a corporate proxy.

#'

#' @keywords internal

add_gremlins_assets <- function() {

  }

  )

}

#' Initialize CI/CD template

#'

#' @inheritParams use_validator

#' @return A yml file with CI/CD steps.

#' @keywords internal

initialize_cicd <- function(cicd_platform) {

  )

    # directory may already exist if user has GA setup

    }

  }

    ),

    }

  )

}

#' Run Shiny app validation tools in your project

#'

#' Run all specified tools and requirements to validate Shiny apps project.

#'

#' @param cran Whether to apply as CRAN check. Defaults to FALSE.

#' @param vignettes Whether to build vignettes. Defaults to FALSE.

#' @param error_on When to raise an error. Possible choices:

#' \code{c("never", "error", "warning", "note")}. Defaults to never.

#' @param timeout Time to wait after starting the subprocess (s). Useful is you know

#' how much time the app takes to load.

#' @param headless_actions Custom code passed as a string to manipulate the app with headless

#' web browser, for instance

#' \code{"headless_app$set_inputs(obs = 200); headless_app$run_js('1+1');"}.

#' If NULL, the app will undergo a classic random Monkey test session.

#' @param workers Number of workers for shinycannon. Default to 5.

#' @param scope Project scope. Accepted values \code{c("manual", "DMC", "POC")}.

#' @param output_validation Whether to compare output snapshots for

#' plots and htmlwidgets. Default to TRUE.

#' @param coverage Whether to perform coverage report. Default to TRUE.

#' @param load_testing Whether to perform load test. Default to TRUE.

#' @param profile_code Whether to profile R code. Default to TRUE.

#' @param check_reactivity Whether to check reactivity log. Default to TRUE.

#' @param flow Whether to display project overview. Default to TRUE.

#'

#' @export

audit_app <- function(

  cran = FALSE,

  vignettes = FALSE,

  error_on = "never",

  timeout = 5,

  headless_actions = NULL,

  workers = 5,

  scope = c("manual", "DMC", "POC"),

  output_validation = FALSE,

  coverage = TRUE,

  load_testing = TRUE,

  profile_code = TRUE,

  check_reactivity = TRUE,

  flow = FALSE

) {

  # Technical requirements

  # Scope

  # Run check

  # Run crash test

  # Output validation

  } else {

  }

  # Load test, profiling, reactlog

  }

  # Generate report with tabs

  )

}

#' Checks to run before running the audit tools

#'

#' Useful for \link{audit_app}. Briefly, we expect the user

#' to have shinycannon and Chrome installed since they are required

#' for loadtest, headless testing ...

#'

#' @return Error if any of the requirement is not met.

#' @keywords internal

check_audit_requirements <- function() {

  }

  )

  }

}

#' Start run_app as background process

#'

#' Required by \link{start_r_bg}.

#'

#' @keywords internal

shiny_bg <- function() {

}

#' Start shinyloadtest recorder in the background

#'

#' Required by \link{start_r_bg}.

#'

#' @param shiny_port Port where runs the shiny apps. This is automatically

#' detected in \link{start_r_bg}.

#'

#' @keywords internal

recorder_bg <- function(shiny_port) {

  )

}

#' Start Shiny + profvis recorder in the background

#'

#' Required by \link{start_r_bg}.

#'

#' @keywords internal

profile_bg <- function() {

    {

    },

  )

}

#' Start run_app as background process

#'

#' Also enables reactlog.

#'

#' Required by \link{start_r_bg}.

#'

#' @keywords internal

reactlog_bg <- function() {

}

#' Start background R process

#'

#' Start process in the background. Required by

#' \link{record_app}, ...

#'

#' @param fun Passed to \link[callr]{r_bg}.

#'

#' @return Process or error

#' @keywords internal

start_r_bg <- function(fun) {

  } else {

  }

  )

  }

}

#' Lint R code within project

#'

#' Uses the `{lintr}` package to check all R sources in provided paths.

#' To fine tune the lintr behavior, edit the `.lintr` file.

#'

#' @param paths Paths to check.

#' @param tolerance Errors to allow. Default to 0.

#' @export

lint_code <- function(paths = "R", tolerance = 0) {

  }

}

#' Build and check package

#'

#' @inheritParams audit_app

#'

#' @return Build and check package. Results are inserted into the

#' main HTML report.

#' @importFrom shiny tags HTML tagList

#' @export

check_package <- function(cran = FALSE, vignettes = FALSE, error_on = "never") {

    ),

  )

  # Avoids any error if test folder does not exist.

  # It is possible that people don't have tests at the

  # begining but still want to run loadtest and profiling ...

        )

      )

    )

  } else {

  }

  )

  # count failed tests if tests exist ...

        "|"

    )

  } else {

  }

  # Prepare check tab UI

              } else {

              },

            )

          ),

                )

              } else {

              }

            )

          )

        )

      })

    ),

  )

  )

}

#' Create message container

#'

#' Useful to display R CMD check elements like errors

#'

#' @param el Element such as list of errors, warnings...

#'

#' @keywords internal

create_message_div <- function(el) {

  )

      )

    })

  }

}

find_pkg_suggests <- function(path = "./DESCRIPTION") {

  }

      }

    } else {

    }

  }

}

copy_shiny_app_files <- function() { # nocov start

  if (!dir.exists("R")) dir.create("R")

  file.copy(

    from = system.file("tests/app_server.R", package = "shinyValidator"),

    to = "./R/app_server.R"

  )

  file.copy(

    from = system.file("tests/app_ui.R", package = "shinyValidator"),

    to = "./R/app_ui.R"

  )

  file.copy(

    from = system.file("run-app/run_app.R", package = "shinyValidator"),

    to = "./R/run_app.R"

  )

  file.copy(

    from = system.file("tests/utils.R", package = "shinyValidator"),

    to = "./R/utils.R"

  )

} # nocov end

#' Crash test for Shiny app

#'

#' Function required to perform

#' crash test for a Shiny app. Test whether the app starts and

#' whether it stays alive after a series of random clicks (monkey test)

#' or targeted actions.

#'

#' @note If the Shiny app takes time to load, you may pass load_timeout

#' parameter with duration in ms. For instance load_timeout = 5000,

#' would wait 5 seconds.

#'

#' @inheritParams audit_app

#'

#' @return Errors if any of the step fails.

#'

#' @export

run_crash_test <- function(timeout = 5, headless_actions = NULL) {

  )

  # By default AppDriver$new waits for shiny to be IDLE 200ms

  # after the initial timeout. No need for extra waiting here.

  # cleanup ports

        )

      })

    ),

  )

}

#' Inject and call gremlins

#'

#' Internally required by \link{run_monkey_test}. Tries

#' to workaround any proxy settings

#'

#' @inheritParams run_monkey_test

#' @keywords internal

call_gremlins <- function(headless_app, screenshot = TRUE) {

  # allows flexibility if running behind proxy

  } else {

  }

  )

  }

      ],

    });"

  )

  }

  # Wait remaining 7 seconds so that gremlins are over

}

#' Perform basic monkey testing

#'

#' Internally required by \link{record_app}, \link{run_crash_test}, ... after

#' the headless connection is opened.

#'

#' @param headless_app Headless app R6 instance.

#' @param screenshot Whether to take screenshot. Defaults to TRUE.

#' @inheritParams run_crash_test

#' @keywords internal

run_monkey_test <- function(headless_app, headless_actions, screenshot = TRUE) {

  } else {

    # Allow \n in case headless_actions had multiple lines

    }

  }

}

#' Generate Shiny app reactlog

#'

#' Runs app in subprocess, controls it with headless browser

#' and generate reactlog file for GitLab CI/CD.

#'

#' @inheritParams audit_app

#'

#' @export

upload_reactlog <- function(timeout = 5, headless_actions = NULL) {

  )

  }

  # shutdown

  # move reactlog artifacts

}

#' Extract and process reactlog

#'

#' Used by \link{upload_reactlog}.

#'

#' @param app Background app.

#'

#' @keywords internal

process_reactlog <- function(app) {

  # move reactlog artifacts

}

#' Create output HTML tab

#'

#' Useful for \link{validate_outputs}.

#'

#' @param done Boolean. Internal to \link{validate_outputs}.

#'

#' @return A shiny HTML tag

#' @keywords internal

create_output_tab <- function(done) {

          )

        )

      })

    )

  } else {

  }

  )

}

#' Validate plot outputs

#'

#' @return For each snapshot folder found in tests/testthat/_snaps

#' save a standalone htmlwidget html page to be included in the final report.

#' @export

validate_outputs <- function() {

      ")

  }

  # loop over all existing snapshots

    # handle htmlwidget vs plots

    # Don't do anything if there is nothing to review

        ),

      )

    } else {

      )

    }

  })

  # Tag to display in the report

}

#' Edit HTML validation report

#'

#' Useful when items are programmatically generated

#' and the HTML output cannot be determined in advance.

#'

#' @param ... Allow for parameter expansion.

#' @param source Document to edit. Defaults to path to overwrite the

#' existing report. Set to NULL to fallback to the shinyValidator original

#' template.

#' @param path Where to write. Default to the global report in /public.

#' @return Modified HTML report in public dir.

#' @importFrom htmltools renderDocument htmlTemplate

#' @keywords internal

edit_html_report <- function(..., source = path, path = "public/index.html") {

      } else {

      },

      ...,

    )

  )

}

#' Create a tab content for HTML report

#'

#' Used by \link{check_package}, ...

#'

#' @param ... Tab content.

#' @param tab_name Unique tab id. Must match that of \link{create_audit_report}.

#' @param title Tab title.

#'

#' @return An HTML tag representing a tab element content.

#' @keywords internal

#' @importFrom htmltools tags

create_tab_content <- function(..., tab_name, title) {

        ),

        ...

      )

    )

  )

}

#' Create a tab menu

#'

#' Useful inside \link{create_audit_report}.

#'

#' @param steps Audit steps: coverage, output validation, load testing, ...

#' @param pkg_name Audited package name.

#' @param pkg_version Audited package version.

#'

#' @return A shiny HTML tag

#' @keywords internal

create_tabs_menu <- function(steps, pkg_name, pkg_version) {

    }),

    )

  )

}

#' Helper to process audit steps

#'

#' Useful for \link{create_audit_report}.

#'

#' @inheritParams use_validator

#'

#' @return A list composed of dynamic and static steps.

#' @keywords internal

create_report_steps <- function(

  output_validation = TRUE,

  coverage = TRUE,

  load_testing = TRUE,

  profile_code = TRUE,

  check_reactivity = TRUE,

  flow = TRUE

) {

  # Steps that are programmatically generated

  )

  # Steps for which report is just iframe

  )

}

#' Create static tabs

#'

#' Useful in \link{create_audit_report}.

#'

#' @param static_steps Provided by \link{create_report_steps}.

#'

#' @return A shiny html tag

#' @keywords internal

create_static_tabs <- function(static_steps) {

      ),

    )

  })

}

#' Inject JS code

#'

#' Necessary to control the report interactivity

#'

#' @param steps CI/CD steps

#'

#' @return An HTML tag containing the script to be inserted in the report.

#' @keywords internal

inject_js_helpers <- function(steps) {

     });",

      )

  )

           })

         ",

      )

    )

  )

}

# Maybe needs to be automated later ...

steps_doc <- c(

  "Package check" = "Package is first built. Any error is shown in case the

  installation fails. Package is checked for consistency

  (style, files, ...). Unit tests are run. Overall you want

  to see all green.",

  "Crash test" = "Crash test ensures the app starts and takes a snapshot

  when the app is loaded. Then, the app is manipulated with headless

  browser and check for alive. Another snapshot is taken.",

  "Output validation" = "The report shows noticed output differences found during unit testing.

  It is the business user responsibility to decide whether to accept the

  difference(s).",

  "Coverage" = "Code coverage shows the amounts of code covered by unit tests.

  The higher the coverage, the higher the package reliability

  (assuming relevant unit tests).",

  "Load test" = "Load testing consists of checking whether the app can support multiple

  simultaneous sessions with reasonable performances.

  If you see a lot of blue area in the session tab, the app is

  likely not very well optimized.",

  "Reactivity" = "{reactlog} represents the reactive graph of the Shiny app.

  It is useful to identify and fix reactivity-related issues.",

  "Code profile" = "{profvis} runs the app and returns the time taken by the R code

  to finish. The lower the result, the higher the performances.

  It is useful to identify bottlenecks.",

  "Project structure" = "{flow} displays the overall project structure."

)

globalVariables("steps_doc")

#' Create a tab menu for HTML report

#'

#' @inheritParams use_validator

#' @param ... To pass extra parameters to \link{edit_html_report}.

#'

#' @return A tab menu used to navigate through \link{create_tab_content}

#' elements.

#' @keywords internal

create_audit_report <- function(

  output_validation = TRUE,

  coverage = TRUE,

  load_testing = TRUE,

  profile_code = TRUE,

  check_reactivity = TRUE,

  flow = TRUE,

  ...

) {

  )

  # Return all steps (dynamic steps + static steps)

  # Setup HTML report (needs source = NULL to start from clean report)

    # Inject JS helpers

    # passed from top level function (see audit_app)

    ...,

    # Handle tabs that are just iframe (load-test, profile, reactlog, coverage, flow)

  )

}

#' Record a Shiny session

#'

#' Start Shiny app as local R subprocess. Connect the

#' shinyloadtest recorder and connect Chrome to the recorder.

#' Manipulate the headless Chrome and close connection. shinycannon

#' replays

#'

#' @inheritParams audit_app

#'

#' @export

record_app <- function(timeout = 5, headless_actions = NULL, workers = 5) {

  # start app + recorder

  # start headless chrome (points to recorder!).

  # AppDriver also support remote urls.

  )

  # clean

  # needed to avoid

  # java.lang.IllegalStateException: last event in log not a

  # WS_CLOSE (did you close the tab after recording?)

  # shinycannon (maybe expose other params later ...)

    )

  )

  # Treat data and generate report

  )

}

#' Include Shiny app validation tools in your project

#'

#' Setup all necessary tools and requirements to validate Shiny apps project.

#' This function is the first to be called.

#'

#' @param cicd_platform CI/CD engine. GitLab or GitHub Actions.

#' When gitlab-docker is selected, we leverage docker executor.

#' The provided CI/CD template will pull docker image from

#' \url{https://hub.docker.com/repository/docker/divadnojnarg/shinyvalidator-docker},

#' which provides installation of R, shinycannon, Chrome, necessary to

#' run the pipeline without issue. This is typically the easiest setup since

#' the classic GitLab CI/CD templates assumes that your GitLab runner has

#' everything installed, which is not necessarily the case.

#'

#' @details By default, the package is checked, built and test are run.

#' Also, we quickly check if the Shiny application is able to start and run

#' without crashing.

#' @export

use_validator <- function(cicd_platform = c("github", "gitlab-docker", "gitlab")) {

  # setup prerequisites

  # CI/CD

  # Add lintr

  # Add gremlins.js assets

  # Copy R/run_app.R

  # treat .Rbuildignore

  # Add suggested pkgs to DESCRIPTION + install them in renv library

}

#' Profile a shiny app

#'

#' Start Shiny + profvis in the background. Chrome connects

#' to the app and then closes to interrupt profvis.

#' The profile report is then saved and exported in the public

#' folder needed for CI/CD.

#'

#' @inheritParams audit_app

#'

#' @return Write a .Rprof file to be reused by CI/CD to publish the report on GitLab pages

#' @export

profile_app <- function(timeout = 5, headless_actions = NULL) {

  # chrome is just needed to trigger onSessionEnded callback from app_server

  )

  }

}