User Code Actions

A user code action is used in situations where standard out-of-the-box features provided by the recorder are not enough. Here are some examples where user code actions could be convenient.

User-specific Validation
Accessing test case related data and parameters
Extended reporting

Looking at a recording file in the project's view you will see that each recording has two associated code files.

: Recording 'AddNewEntry' has two code file items

Note: User code actions are not available within the standalone Recorder.

Within Ranorex Studio, each recording manages two types of source code files:

Automatically generated main recording source code file
<RecordingName>.<CodeFileExtension>
User specific source code file <RecordingName>.UserCode.<CodeFileExtension>

You can jump to the generated code of a recorded action by right-clicking the action and choosing 'View Code' from the context menu.

: Jump to generated code of a recorded action

Every time you change and save a recording, the main code file 'AddNewEntry.cs' is newly generated. Any change of code should always be made within the recording's UserCode.cs file.

Create User Code Actions

You can create user specific code actions by converting existing items or by adding a new 'Usercode' action item via the toolbar button 'Add New Action'.

: Convert an existing action item to a code action

: Specify method name used for user code item

: Use the context menu item 'View Code' to jump into the code

After the creation of a new user code action within the actions table, a new method is added to the partial class of the recording. If you're converting an existing action item, the code generated for the main recording file is transferred to the new user code method.

C#

namespace MyFirstTestProject
{
    public partial class AddNewEntry
    {
        /// <summary>
        /// This method gets called right after the recording has been started.
        /// It can be used to execute recording specific initialization code.
        /// </summary>
        private void Init()
        {
            // Your recording specific initialization code goes here.
        }

        public void ClickOnPasswordField()
        {
            Report.Log(ReportLevel.Info, "Mouse", "Mouse Left Click item 'FormAdd_Entry.TabPageList.InputFields.TextPassword' at 175;9.", repo.FormAdd_Entry.TabPageList.InputFields.TextPasswordInfo);
            repo.FormAdd_Entry.TabPageList.InputFields.TextPassword.Click("175;9");
        }

    }
}

VB.NET

Namespace MyFirstTestProject
	Public Partial Class AddNewEntry
		''' <summary>
		''' This method gets called right after the recording has been started.
		''' It can be used to execute recording specific initialization code.
		''' </summary>
		Private Sub Init()
			' Your recording specific initialization code goes here.
		End Sub

		Public Sub ClickOnPasswordField()
			Report.Log(ReportLevel.Info, "Mouse", "Mouse Left Click item 'FormAdd_Entry.TabPageList.InputFields.TextPassword' at 175;9.", repo.FormAdd_Entry.TabPageList.InputFields.TextPasswordInfo)
			repo.FormAdd_Entry.TabPageList.InputFields.TextPassword.Click("175;9")
		End Sub

	End Class
End Namespace

User Code Actions and Parameters

Since Version 3.3 it is possible to use parameters for user code actions. You can pass (string) values to your user code methods to gain more flexibility in your testing environment.

To use parameters for a new user code action, simply click the cell next to the method's cell and type in a value to be used as a parameter (e.g. 'WordPressDemo').

: User Code Action with a parameter

Of course you are also able to use more than one parameter for each action. If there are no more columns available (maximum of three in the GUI), you can use the browse button to access the Ranorex Argument Editor.

: Browse button to access the Ranorex Argument Editor

To enhance flexibility, you can use variables instead of hardcoded values. This can be done in the usual way.

: Create a new variable to be used as a parameter

You'll find an overview of existing parameters in the Ranorex Argument Editor. Here you can also name existing parameters and add additional parameters.

: Ranorex Argument Editor for handling user code parameters

After declaring the parameters with values or variables, you can switch to the user code method and use the passed parameters..

C#

public void AddEntryWithParams(string aTitle, string aUsername, string aPassword, string aURL)
{
 MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository.Instance; 
	
 // Set text fields
 MyRepo.AddEntry.TabSheetAddEntry.Title.TextValue = aTitle;
 MyRepo.AddEntry.TabSheetAddEntry.UserName.TextValue = aUsername;
 MyRepo.AddEntry.TabSheetAddEntry.Password.TextValue = aPassword;
 MyRepo.AddEntry.TabSheetAddEntry.Repeat.TextValue = aPassword;
 MyRepo.AddEntry.TabSheetAddEntry.URL.TextValue = aURL;
}

VB.NET

Public Sub AddEntryWithParams(aTitle As String, aUsername As String, aPassword As String, aURL As String)
	MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository.Instance
	
	' Set text fields
	MyRepo.AddEntry.TabSheetAddEntry.Title.TextValue = aTitle
	MyRepo.AddEntry.TabSheetAddEntry.UserName.TextValue = aUsername
	MyRepo.AddEntry.TabSheetAddEntry.Password.TextValue = aPassword
	MyRepo.AddEntry.TabSheetAddEntry.Repeat.TextValue = aPassword
	MyRepo.AddEntry.TabSheetAddEntry.URL.TextValue = aURL
End Sub

Additionally to creating method calls in Ranorex Recorder you are able to define your methods in code and just select the intended method in the Recorder Table. Here you are also able to choose overloaded methods.

: Choose one of the overloaded method calls

: Ranorex Argument Editor with arguments and variable binding from overloaded method

Conditions in Code

Another reason for writing user code is to read text values from UI elements like text boxes and to reuse them for conditional automation steps.

Note: Only create small and easy to maintain user code actions for a recording. If an implemented method should also be available for other test cases, create a code module (see Lesson7: Code Modules) instead.

Within the 'DeleteEntry' recording that was created in Lesson 3: Data-Driven Testing, there are three simple actions for deleting the selected entry (selecting the item, opening the context menu and choosing the context menu item). As you can see it is meaningful to only delete an entry if it is selected. To accomplish this, code with a condition can be used.

As a first step, open the 'DeleteEntry' recording and select the last two items as only they should be executed if the entry is selected. Click on the 'Merge Items to User Code Item' menu item in the context menu.

: Context menu item to 'Merge Items to User Code Item'

After doing this, these two actions are merged into one user code action. Give this method a meaningful name (e.g. 'DeleteItemIfFocused'). Switch into the code view by clicking on the context menu item 'View User Code'. Now change the converted code so it is only executed if the cell is focused on.

C#

public void DeleteItemIfFocused()
{
	if (repo.MainForm.Entry.HasFocus) {
		
		Report.Log(ReportLevel.Info, "Mouse", "Mouse Right Click item 'MainForm.Entry' at 127;10.", repo.MainForm.EntryInfo);
   		repo.MainForm.Entry.Click(System.Windows.Forms.MouseButtons.Right, "127;10");
   		
   		Report.Log(ReportLevel.Info, "Mouse", "Mouse Left Click item 'KeePass.DeleteEntry' at 168;14.", repo.KeePass.DeleteEntryInfo);
   		repo.KeePass.DeleteEntry.Click("168;14");
	}
	
}

VB.NET

Public Sub DeleteItemIfFocused()
	If repo.MainForm.Entry.HasFocus Then

		Report.Log(ReportLevel.Info, "Mouse", "Mouse Right Click item 'MainForm.Entry' at 127;10.", repo.MainForm.EntryInfo)
		repo.MainForm.Entry.Click(System.Windows.Forms.MouseButtons.Right, "127;10")

		Report.Log(ReportLevel.Info, "Mouse", "Mouse Left Click item 'KeePass.DeleteEntry' at 168;14.", repo.KeePass.DeleteEntryInfo)
		repo.KeePass.DeleteEntry.Click("168;14")
	End If

End Sub

Online User Guide

Download Test Automation Guide
(PDF file, 20MB)

Online API Documentation