From cfff8fb5c3f46091f5cb110338ebffe6f37e88e3 Mon Sep 17 00:00:00 2001 From: laijasmine Date: Thu, 18 Feb 2021 15:05:59 -0800 Subject: [PATCH] update the readme so the testing procedures are more clear with step by step instructions so mistakes are less likely to be made --- README.md | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a335fc2..3b082f3 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ The NSF awards bot regularly contacts principal investigators with reminders on ## How the bot works Every 24 hours the bot queries NSF's award [API](https://www.research.gov/common/webapi/awardapisearch-v1.htm) for newly awarded grants and stores this information in a pre-existing database. When it finds a new award it creates a new ticket in [Request Tracker](https://bestpractical.com/request-tracker/) and sends an initial correspondence that outlines project-specific expectations and deadlines. It sends reminders to submit annual reports, submit data for Arctic Observing Network (AON) projects, and that the award is expiring soon. The bot sends error messages to a slack channel. -## Setup for testing locally +## Setup - Copy the bot [cron script](https://github.com/NCEAS/awards-bot/blob/master/inst/main_cron_script.R) to a directory -- Create a file called `.Renviron` in the same directory as the script. the `.Renviron` can be accessed by `usethis::edit_r_environ()` +- Create a file called `.Renviron` in the same directory as the script. Include the following variables: ```text DATABASE_PATH # Path to the database of awards and correspondences @@ -23,9 +23,6 @@ Every 24 hours the bot queries NSF's award [API](https://www.research.gov/common INITIAL_AON_OFFSET=11 # Number of months after award startDate to send first AON data due reminder AON_RECURRING_INTERVAL=6 # Number of months to send recurring emails for AON data due ``` - -- If you have issues logging in you might need to install the development branch of rt `remotes::install_github("nceas/rt@develop")` -- If you are running locally you might need to set up slackbot `slackr::slackr_setup(channel = "#awardbot",incoming_webhook_url = Sys.getenv("SLACK_WEBHOOK_URL"))` **Note** - please contact Chris for set up in Linux @@ -47,11 +44,35 @@ In this example we will assume the submission policies changed to require an ini - Unit tests!! ## Testing the bot -The awards-bot package contains modular unit tests, however, many of these don't run, by default, unless the R session is connected to [RT](https://bestpractical.com/request-tracker/) and [Slack](https://slack.com/). If you need to test the bot for any reason run the [test_main unit test](https://github.com/NCEAS/awards-bot/blob/master/tests/testthat/test_main.R) locally, ideally line by line. Be aware that this will create two test tickets in RT. A thorough test of the bot would involve signing in to RT and Slack, and running `devtools::check()`; although, if the [test_main unit test](https://github.com/NCEAS/awards-bot/blob/master/tests/testthat/test_main.R) passes it's generally safe to assume the more modular tests will pass as well. +The awards-bot package contains modular unit tests, however, many of these don't run, by default, unless the R session is connected to [RT](https://bestpractical.com/request-tracker/) and [Slack](https://slack.com/). A thorough test of the bot would involve signing in to RT and Slack, and running `devtools::check()`; although, if the [test_main unit test](https://github.com/NCEAS/awards-bot/blob/master/tests/testthat/test_main.R) passes it's generally safe to assume the more modular tests will pass as well. + +General notes: - only use `awardsBot:::test_main()` in testing. This a wrapper for `awardsBot::main()` except with an additional `email` argument - set `email = your test email address` in the unit test script - modify `test_main()` calls in the unit test script accordingly, including any additional arguments + +### Testing Locally +Please follow this closely so no emails are sent to researchers by mistake while testing. + +1. Add the following lines to the `.Renviron` (can be accessed by `usethis::edit_r_environ()`) +``` + SLACK_WEBHOOK_URL="{URL}" # Your Slack webhook URL + RT_URL="https://example.com/rt" # The URL of your RT install + RT_USER="your_rt_user" # Your RT username + RT_PASS="your_rt_password" # Your RT password +``` + +2. Set up slackbot: `slackr::slackr_setup(channel = "#awardbot",incoming_webhook_url = Sys.getenv("SLACK_WEBHOOK_URL"))` + +3. Login to RT: `rt::rt_login()` + +4. Run `devtools::load_all()` to source the scripts for testing so you can run the test file line by line + +5. Run the [test_main unit test](https://github.com/NCEAS/awards-bot/blob/master/tests/testthat/test_main.R) locally, ideally line by line. + +6. Two test tickets should be created in RT. + ## Style Code generally follows the [tidyverse style conventions](http://style.tidyverse.org/), with the following specific style preferences: - underscore for all variable names unless referring to an NSF awards API return field (i.e. expDate, startDate, etc.)