Automation of Legacy Applications with the GDI Capture Plug-In

To set up test automation scripts, recognition of the UI objects under test is necessary. In some cases, Ranorex cannot access all the UI objects of the application under test (e.g. VB6, MFC, older Delphi versions). That’s why we developed the GDI Capture Plug-In (beta), which enables capturing and recognition of text elements drawn using GDI functions within the application under test.

These elements can then be used within the RanoreXPath as “RawText” and “RawTextBlock” capability. Both are added as children to existing Win32 windows or controls (NativeWindow capability). The RawText capability represents a single text line or string. The RawTextBlock combines the contents of all RawText strings into a single text block.

• Set up the GDI Capture Plug-In
• GDI Capture Plug-In Example Project

Set up the GDI Capture Plug-In

1. Please close all Ranorex tools
2. Download and extract the GDI Capture Plug-in (zip) (works with Ranorex 2.3.4 and all higher 2.3.X versions; there is no need to install the plugin with Ranorex 3.X versions as 3.X already includes that plugin natively) to following location“C:\Documents and Settings\All Users\Application Data\Ranorex2\Plugins” (for Windows XP) or “C:\ProgramData\Ranorex2\Plugins” (for Vista, 7)”
3. Now you have to configure the plug-in to enable capturing of the text for your application. Therefore, please open the “Ranorex.Plugin.RawTextPlugin.config” file and change following line in XML File

   <include type="process" name="notepad"/>

   to following (to check the process name of your application please use Spy or the Task Manager)

   <include type="process" name="YourApplicationProcessName"/>

4. You can also use the process name of your application in the config file. Please use the

   <include type="class" name="MyCustomWndClass"/>

   statement in your XML-Config file. To get the class name of your element please use Spy and track your element. At the overview tab you will find the class name.

   You can also use RegEx in your config file to automate more than one classes. For example all classes which starts with “Afx”

   <include type="class" name="Afx.*"/>

   Whole XML-Config File:

   <!--
   Configuration for GDI Capture Plug-In
   -->
   <rawtextconfig>
   <!--
   Example for by process filtering <include type="process" name="calc"/>
   -->
   <!--
   Example for by class name filtering <include type="class" name="MyCustomWndClass"/>
   -->
   <include type="process" name="YourApplicationProcessName"/>
   </rawtextconfig>

5. Start Ranorex Spy and check if the GDI Capture Plug-In was successfully loaded. Therefore, please open the About Dialog by clicking the Ranorex Logo and check if the RawText is loaded.


GDI Capture Plug-In successfully loaded

6. Start your application and Spy. Now you should be able to track the RawText/RawTextBlock of your elements. You also should recognize a short flicker of your application when you track an element. That’s the new GDI Capture Plug-In which forces your software to redraw.

On the screenshot below you can see the text elements of the menu bar of the application under test:

GDI Capture Plug-In Example Project

Create a new Project in Ranorex Studio and use the new GDI Capture Plug-In in code. After the project is created, please add a new reference to be able to access the Plug-In. Therefore right-click references and select the Ranorex.Plugin.RawText.dll from the Plug-In folder (the same folder as used above to install the Plug-In). If the DLL is successfully added, create two new methods called CreateNewDocument and CheckIfTextExists.
These two methods should look like following:

CreateNewDocument

private static void CreateNewDocument(Ranorex.Form form)
{
	//Searching for the menu "File" using the RawText capability
	RawText MenuFile = form.FindSingle(".//rawtext[@caption='File']");
	//Click the menu "File"
	MenuFile.Click();
	Report.Log(ReportLevel.Info, "Info", "File menu clicked");
	Delay.Ms(500);

	//Popup form for the menu items
	Ranorex.Form IdleForm = "/form[@title='']";
	//Now searching for the new Button to create a new document
	RawText MenuItemNew = IdleForm.FindSingle(".//rawtext[@caption='New']");
	//Click the menu entry to create a new document
	MenuItemNew.Click();
	Report.Log(ReportLevel.Info, "Info", "New menu item clicked");

	//Check if the new document was created succesfully
	Validate.Exists(form.FindSingle(".//rawtext[@caption='MFC_Test2']"));
}

CheckIfTextExists

private static void CheckIfTextExists(RawTextBlock TextBlock, string CheckString)
{
	Report.Log(ReportLevel.Info,"Text", "Check if the string exists in RawTextBlock");

	//If the CheckString value is available in TextBlock. Report will report succes.
	//If not available Report will report Error
	if(TextBlock.RawText.Contains(CheckString))
	{
		Report.Log(ReportLevel.Success,"Text", "Is available in RawTextBlock '" + TextBlock.RawText + "'");
	}
	else
	{
		Report.Log(ReportLevel.Error,"Text", "Is not available in RawTextBlock '" + TextBlock.RawText + "'");
	}
}

Please download the following MFC sample application SampleApplication.zip and place it in your project folder on your hard drive.

Add following code to your main method:
Main

STAThread]
public static int Main(string[] args)
{
    Keyboard.AbortKey = System.Windows.Forms.Keys.Pause;
    int error = 0;

    string logFileName = "Test.rxlog";

    Report.Setup(ReportLevel.Info, logFileName, true);

    try
    {
        //Start the MFC Application
        System.Diagnostics.Process.Start("..\\..\\MFC_Test.exe");

        //Wait for process
        Delay.Seconds(5);

        //Form of MFC Application
        Ranorex.Form form = "/form[@processname='MFC_Test']";

        //Bring form to foreground and activate it
        form.EnsureVisible();
        form.Activate();

        //Call the method to create a new document
        CreateNewDocument(form);

        //Call method to check if string exists in element
        CheckIfTextExists(form.FindSingle(@".//rawtextblock[@caption~'^This\ is\ a\ caption\ bar\ whe']"),
                          "presented");

        //Close the Application
        Ranorex.Button CloseButton = "/form[@processname='MFC_Test']/titlebar/button[@accessiblename='Close']";
        CloseButton.Click();
    }
    catch (Exception e)
    {
        Report.Error("Unexpected exception occured: " + e.ToString());
        error = -1;
    }

    Report.End();
    return error;
}

Last but not least you have to configure the GDI Capture Plug-In, to be able to access drawn text elements within the application under test. Therefore please take a look at “Step 3″ of “Set up the GDI Capture Plug-In” and add following line to your configuration file

<include type="process" name="MFC_Test"/>

If the above steps are finished, please compile your project and execute it. Ranorex should be able to automate the “Menu Bar” of the MFC Feature Pack Application.

Download the GDI Plug-In Example Solution (GDIPluginExample.zip)

Tags: Accessibility, Code Samples, Legacy Applications, Technology