Skip to contents

Get started with arthelpers

Source: vignettes/arthelpers.qmd

What is arthelpers?

arthelpers is an internal developer tools package for Artalytics R package development. It provides utilities that streamline common development tasks including environment diagnostics, GitHub repository management, Shiny app testing, package documentation setup, and test data cleanup.

Unlike production packages (artcore, artutils, artgemini), arthelpers sits in platform/misc/ as a meta-development tool. It’s used during package development but is not part of the production dependency chain.

Key capabilities

  • Environment diagnostics: Inspect package context, dependencies, and system info
  • GitHub operations: List and document organization repositories
  • Shiny testing: Capture visual screenshots of Shiny apps
  • Package setup: Automate favicon and logo configuration for pkgdown/Quarto sites
  • Database cleanup: Delete test data from database and CDN during development

A Complete Workflow: Setting Up a New R Package

This workflow demonstrates how to use arthelpers when initializing a new Artalytics R package with proper branding and documentation.

Every Artalytics package should have consistent branding. Use setup_favicon() to automate logo download and favicon generation:

library(arthelpers)

# Auto-detect project type (pkgdown vs Quarto) and setup branding
setup_favicon()

What this does: - Detects whether you’re working on a pkgdown site (_pkgdown.yml) or Quarto site (_quarto.yml) - Downloads the Artalytics logo from CDN to the appropriate directory - Generates a complete favicon set (favicon.ico, apple-touch-icon.png, etc.) via API - Places files in the correct locations for pkgdown (pkgdown/favicon/) or Quarto (www/assets/favicon/)

Custom branding:

# Use a different logo URL
setup_favicon(url = "https://example.com/custom-logo.png")

# Force regeneration if files already exist
setup_favicon(overwrite = TRUE)

Step 2: Verify Development Environment

Before committing changes or reporting issues, verify your package environment is configured correctly:

# Print environment summary
describe_env()

Output includes: - Active package name and version - Non-sensitive environment variables (credentials masked automatically) - Direct GitHub dependencies from DESCRIPTION Remotes field - Installed versions of dependencies - System info (R version, platform, OS)

Programmatic use:

# Get environment info without printing
env_info <- describe_env(quiet = TRUE)

# Check if specific dependency is installed
if ("artcore" %in% names(env_info$deps_versions)) {
  cat("artcore version:", env_info$deps_versions["artcore"], "\n")
}

Step 3: Document Available Repositories

When writing documentation that references other Artalytics packages, generate a current repository index:

# List all repos for the organization (requires GITHUB_PAT)
repos <- get_repo_index()

# View the data.table
print(repos)
#>      repo_name visibility                  description
#> 1:    artcore    private  Infrastructure layer...
#> 2:   artutils    private  Data access layer...
#> 3:  artgemini    private  Google Gemini wrapper...

# Use markdown links in documentation
cat(repos$repo_md, sep = "\n")
#> [artcore](https://github.com/artalytics/artcore)
#> [artutils](https://github.com/artalytics/artutils)

Query different organizations:

# List repos for another organization
tidyverse_repos <- get_repo_index(org = "tidyverse")

Another Workflow: Shiny App Visual Testing

When developing Shiny apps, visual regression testing helps catch UI issues. Use screenshot_app() to capture app screenshots:

library(shiny)
library(arthelpers)

# Create a simple test app
app <- shinyApp(
  ui = fluidPage(
    titlePanel("Test App"),
    sidebarLayout(
      sidebarPanel(
        sliderInput("n", "N:", min = 1, max = 100, value = 50)
      ),
      mainPanel(
        plotOutput("plot")
      )
    )
  ),
  server = function(input, output) {
    output$plot <- renderPlot({
      hist(rnorm(input$n))
    })
  }
)

# Take screenshot using default method (webshot2)
screenshot_app(app, file = "test-app.png")

Choosing the Right Method

arthelpers supports three screenshot methods, each with different tradeoffs:

webshot2 (default):

screenshot_app(app, method = "webshot2")
  • Fast and lightweight
  • Best for static screenshots
  • Requires Chrome/Chromium installed

shinytest2:

screenshot_app(app, method = "shinytest2", wait_for_idle = TRUE)
  • Integrated with shinytest2 testing framework
  • Waits for Shiny reactivity to settle
  • Best for testing dynamic apps with reactive elements

chromote:

screenshot_app(app, method = "chromote", port = 8888)
  • Low-level Chrome DevTools Protocol control
  • Maximum flexibility for custom wait logic
  • Best for complex scenarios needing fine-grained control

Capturing Specific Elements

Use CSS selectors to screenshot specific UI components:

# Screenshot only the plot, not the full page
screenshot_app(app, selector = "#plot", file = "plot-only.png")

# Screenshot with custom viewport size
screenshot_app(
  app,
  vwidth = 1920,
  vheight = 1080,
  file = "large-viewport.png"
)

Database Cleanup During Development

When testing artwork uploads or artist creation, use the delete functions to clean up test data:

library(arthelpers)

# Delete a test artwork (database only)
delete_artwork(
  artwork = "99a61148-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
)

# Delete artwork and CDN files
delete_artwork(
  artwork = "99a61148-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  delete_cdn = TRUE
)

# Delete entire artist and all their artworks
delete_artist(
  artist = "746b8207-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  delete_cdn = TRUE
)

IMPORTANT: These functions are marked experimental and should never be used in production. They permanently delete data without confirmation prompts.

Batch Deletion with Shared Connection

For deleting multiple records, pass a shared database connection to avoid connection overhead:

library(artcore)

# Create connection
cn <- ..dbc()

# Delete multiple artworks
artworks <- c(
  "99a61148-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "99b72259-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
)

for (art in artworks) {
  delete_artwork(artwork = art, delete_cdn = TRUE, cn = cn)
}

# Close connection when done
..dbd(cn)

Environment Variables

See the README for complete environment variable configuration. The README is the single source of truth for all required variables.

Next Steps