Testing and Debugging Scripts
For tips and guidance on how to develop portable R code using the deployrUtils package, see the Writing Portable R Code guide on the DeployR website.
Use the Test page to do the following to repository-managed scripts:
- Test and verify the functioning of scripts you own
- Debug and fix the functioning of scripts you own
- Test and verify the functioning of scripts to which you have access rights
- Debug the functioning of scripts to which you have access rights
The Test page is divided into four panes:
Source pane (1): displays the actual R source code contained in the script file
Debug Console Output pane (2): displays the R session console output generated during the execution of a script
Script Execution Parameters pane (3): allows you to interact with the inputs defined in the code and define simple inputs on-the-fly.
Artifacts pane (4): allows you to see the files and plots produced when the code was last executed as well as inspect the API request and response markup.
To access the Test page:
- Open a script and click the Test button on the right of the File Properties page. The Test page opens.
Each time you log into the Repository Manager, you are automatically allocated a dedicated R session, which supports all of your R script testing and debugging within the Repository Manager. This R session lives for the duration of your HTTP session, until you logout or timeout, at which point it is released. You can load data into the R session as well as clear the workspace and working directory.
The Source pane presents the script’s R code. The extent to which you can interact with the source code depends entirely on permissions and policies. Viewing R Code
In this pane, you can view and scroll through the source code of the R script. Code elements are color-coded for your convenience.
If you do not own this file and cannot see the code in the Source pane, then a server policy was changed by your administrator. An onscreen alert will also appear.
Only the owners of a file can edit the source code of the Latest version of a script. This pane is not meant to be used to write scripts or make major changes to your scripts. It is not a substitute for your favorite IDE for R. However, to facilitate the debugging process, the owners of a file can use this pane to make small changes, save those changes to the repository, and test them out.
To edit the R code:
Find the code you want to change in the Source pane or position your cursor where you want to write new code.
Type your edits directly into the pane.
Only file owners who were assigned the POWER_USER role by the administrator have the permissions to run snippets of code in the Source pane. If you are a file owner assigned the POWER_USER role, you can select and run snippets from the Source pane and inspect the workspace in the Debug Console Output pane to see the R objects within and their values.
Any DeployR user who can access a script can also test that script by running the script, changing the input values, and then running it again in the Test page.
When debugging a script, you may need to interrupt an execution.
You can run a script in the Test page using the script's source code as-is regardless of whether or not any inputs were defined using deployrInput().
To run a script with the default values and inputs:
Make no changes in the Script Execution Parameters pane.
Click Run in the toolbar. This script is run in its entirety. Any artifacts are then displayed in the Artifacts pane.
### Running Entire Scripts with Modified Inputs
You can supply new and modified input values for a script, and then pass those input values when executing the script.
Supply new input values in the following ways:
Defining temporary primitive input values on-the-fly
Modifying the value of any deployrInput() widgets
Editing the source code to add, remove, or update any deployrInput() functions (available to script-owners only)
For tips and guidance on how to develop portable R code using the deployrInput function from the deployrUtils package, see the Writing Portable R Code guide on the DeployR website.
To run a script new and modified input values:
Open the script.
Go to the Test page.
In the Script Execution Parameters pane, click Run in the toolbar. The input values are passed along from this pane, and the script is run in its entirety.
### Running Snippets of Code
If you own the script and have POWER_USER permissions, you can run a snippet of code directly from the Source pane. In this way, you can make small changes to your R code and run only the lines you want to test. You can even select a variable name, for example, and run that to see its contents.
Running code from the Source pane will run the selected code as-is without taking into account any modified values or Quick Inputs defined in the Script Execution Parameters pane.
To run code selections:
Open the script
Go to the Test page.
In the Source pane, select the code that you want to run. If no code is selected, the current line is used.
Press
Ctrl-Enter
on Windows/Linux orCommand-Enter
on MAC. The code is executed on the server and the response is displayed in the Debug Console Output and Artifacts panes.
In the Debug Console Output pane, you can see all of the R session console output generated during the execution of the code on the DeployR server. Each time code is executed in this Test page, this pane is automatically populated for you.
While this pane bears some resemblance to R's console, the Debug Console Output pane in Repository Manager is designed to help you learn more about your script's behavior for the purposes of debugging the script, not to act as your primary development environment. This Debug Console Output pane executes code exclusively on the server and does not have the same capabilities as a full R console.
If you are an owner assigned the POWER_USER role, you can select and run elements from the Source pane and inspect the workspace here to see the objects and their values.
Although you cannot type anything into the console, you can still clear the pane, the working directory, or the workspace.
The Files & Plots section of the Artifacts pane presents the files and plots produced when code was last executed in the Test page:
- Any unnamed or named graphical files generated by the R graphics device, which are visually rendered in the pane
- Non-image files written to the working directory, such as .CSV files, binary files, and so on, which appear as clickable links in the pane
These API Request and API Response sections of the Artifacts pane present the execution at the API level. This information is particularly interesting to DeployR client application developers since it provides critical details they can use when building their client applications.
- API Request presents the complete set of parameters sent along to the DeployR server on the script execution API call.
- API Response presents the complete response markup sent back by the DeployR server on the script execution API call.
Upon each code execution, the Artifacts pane is cleared and repopulated.
Each time you log into the Repository Manager, you are automatically allocated a dedicated R session, which supports all of your R script testing and debugging within the Repository Manager. This R session lives for the duration of your HTTP session, until you logout or timeout, at which point it is released.
To help you test and debug your scripts, you can manipulate this underlying R session by:
- Loading and moving data into the R session to be used by one or more of the scripts you are debugging
- Clearing the working directory or workspace of that underlying R session
- Retrieving DeployR-encoded R objects from the workspace
You can load data into the underlying R session from the Test page of any open script. Any type of data file can be loaded into the working directory of the underlying R session. For example, you could load a .CSV file that will be read by your script. However, only files containing binary R objects, typically with a .rData file extension, can be loaded directly into the workspace from this page.
You choose to load data files and binary R objects from the repository or from your local machine. You can always load your files; however, your ability to load data files that you do not own from the repository is determined by server policies.
To load data into the underlying R session:
In the Test page of the open script, click the Load button in the Script Execution Parameters pane toolbar.
- To load a file that already exists in the repository, choose Load File from Repository.
- To load a file from your machine, choose Load File from Local Machine.
In the dialog, select the directory and file containing the data to be loaded.
Specify whether the data should be loaded into the working directory or workspace:
- If you are loading a data file, choose Working directory.
- If you are loading a binary R object, choose Workspace. If necessary, first save your model or other object outside of DeployR as an .rData file, and then load it here.
Click Load to load the data.
If you have loaded data files or R objects into this R session, clearing the workspace and working directory, or even timing out of your user session, will delete the files, data, and R objects you loaded. If that data is still needed, you must reload it.
You can clear the working directory and/or the workspace on the underlying R session using the menu in the Debug Console Output pane toolbar. When you clear the working directory, all data files in your work directory are deleted, including those files output to the working directory by code executions as well as any files you loaded into the working directory. Likewise, if you clear the workspace, all binary R objects and data models are cleared from the underlying R session workspace including those generated by code executions and those loaded into the workspace.
If your user session times out, the underlying R session is released.
To clear the pane, workspace or working directory:
Click the arrow next to the Clear button in the Debug Console Output pane toolbar to see the Clear submenu options.
Select one of the following options:
- Clear Pane to clear the output visible on the pane without affecting on the underlying R session.
- Clear Workspace to clear all binary R objects or models from the workspace on the underlying R session regardless of whether they were generated during code execution or loaded into the session.
- Clear Working Directory to clear all files from the working directory on the underlying R session.
- Clear Both to clear all binary R objects from the workspace and all files from the working directory on the underlying R session.
There are two kinds of inputs to your script. They are:
- The values for the
deployrInput()
widgets - Primitive name-value pairs in the Quick Inputs field
To help you test your script, you can supply temporary input values in the Script Execution Parameters pane in the upper right. You can then pass these values along during the next execution of your R script in this user session. You can:
- Change any values displayed in the
deployrInput()
widgets - Define some primitive values on-the-fly
- Run the entire script with the values and quick inputs shown in this pane
You can also load data into the underlying R session to be used by any script. For example, you might create a model, save that in an .rData file, and then load it into the workspace so your script can use the model to score new data.
Any inputs defined in the R code using the deployrInput() function, and their default values, appear at the top in this pane. The default values defined in the R code are preselected here for you. You can change the value of an input here, run to test your code using the new value, and then evaluate the outcome.
For tips and guidance on how to develop portable R code using this function from the deployrUtils package, see the Writing Portable R Code guide on the DeployR website. Refer to the deployrUtils package help for more details and examples.
If you do not own this file and cannot see the R code in the Source pane, then the deployrInput() functions cannot be rendered either.
By default, if you can access this file in the Repository Manager, then you are permitted to see any deployrInput
widgets in this pane regardless of whether you own the file or not. However, if you do not own this file but know there are deployrInput
declarations in the code and cannot see them here, it may be due a change in the server configuration policies by the DeployR administrator that prohibits the loading and downloading of files that may contain code into an R session.
You can define some temporary basic inputs on-the-fly to help you test your script. Only primitive values (real, integer, string) are accepted. To define one, enter each input as a comma-separated name-value pair in the Quick Inputs field.
Each input is defined as a comma-separated, name-value pair using the following syntax:
InputName_1, Value_1, InputName_2, Value_2
For example:
Title, "Sales Report", Month, 12
The Quick Inputs field is designed to support primitive inputs, but not complex inputs. Quick Inputs cannot be saved. For those, we recommend defining them in your code using the deployrInput()function. Quick Inputs cannot be saved with the script.
On the Test page, you can retrieve and inspect DeployR encoding for R objects in the underlying workspace. Since DeployR encodings are used to encode R object data on the DeployR API, the R Objects feature is of particular interest to client application developers.
The following kinds of artifacts might be present after you execute code:
- Unnamed and named plots from the R graphics device and non-image files that were written to the working directory
- DeployR encodings of R objects from the workspace
You can use the R Objects field to request that R object(s) in the workspace be returned as a DeployR-encoded object(s) in the response markup.
To learn more about DeployR encoded objects, refer to the DeployR API Reference Guide.
The following is an example a DeployR encoding of an R vector object returned in the API Response tab of the Artifacts pane for the "workspace" property:
{
...
workspace": {
"objects": [
{
"name": "x",
"type": "vector",
"rclass": "numeric",
"value": [
10,
11,
12,
13,
14,
15,
]
}
]
}
...
}
The type property indicates how you can decode the encapsulated data for use within his or her client application.
To retrieve R objects from the workspace:
In the Script Execution Parameters pane, enter the name of an R object that is currently in your workspace or one you expect to be generated from the execution into the R Objects field.
Enter any additional R object names as a comma-separated list, such as
ObjectName1, ObjectName2, ObjectName3, etc.
Run the script in this Test page.
Once the execution has completed, click API Response in the toolbar of the Artifacts pane.
Search for the "workspace" property to find the DeployR encodings of the named objects in the response markup.
You cannot save the list of object names you enter in the R Objects field. This is a temporary field used only to retrieve the DeployR encoding of one or more R objects on-the-fly.
Whenever you run code from anywhere in the Test page, you can interrupt the execution of that code. Since the console output is shown in the Debug Console Output pane, this is also where you can interrupt an execution in progress.
To interrupt a code execution:
During an execution, find the red icon in the Debug Console Output pane toolbar.
Click the red icon on the toolbar to interrupt and terminate the execution.
The changes you make to the source code of your own scripts in the Repository Manager are not saved automatically. If you want to keep any of the changes you make in the Source pane, you must explicitly save them.
Changes you make in the Script Execution Parameters pane to test and debug your script are temporary and cannot be saved.
To save from the Source pane:
After you have made changes to the source code in the Test page, click Save in the Source pane toolbar.
In the submenu, choose one of the following:
- Overwrite Latest version to replace in the current working copy of the script.
- Save as new version to save the changes as the Latest version with an optional comment, and to preserve what was previously the Latest version in the file's history.
Ctrl-S
on Windows/Linux orCommand-S
on MAC will save and overwrite the Latest version.