KeyLib Foundation (EN)

The KeyLib Foundation training introduces you to KeyLib, ALMG’s test automation solution. All exercises and questions should be completed to finish the training. You will receive a KeyLib Foundation Certificate after successfully completing the training.

KeyLib Foundation (EN)

What is KeyLib?

KeyLib is an automation platform that saves you time and improves the quality of your software. You can use KeyLib to easily automate testcases, but also to monitor applications as well as automate (workflow) processes.

How does it work?

KeyLib recognises text and images on a computer screen, which means it works on all platforms and with any application.

No programming knowledge is required to automate tests. We use simple keywords to execute actions on screen.

System configuration

KeyLib uses two systems, one for running KeyLib and a second configured as KeyLib Client to run tests, as well as monitor and automate processes.

KeyLib uses remote access software to make this possible.


In order to complete the KeyLib Foundation training you need a working KeyLib installation (KeyLib software and KeyLib Client). Contact your systems administrator if you don't have access to KeyLib.

Question: Which applications can be tested with KeyLib?

  • Only web-based applications
  • Only Windows applications
  • Only Windows and web-based applications
  • Any application on any type of platform

Activity: Starting KeyLib

  • Start KeyLib by double-clicking the KeyLib icon on the desktop
  • Enter the user name and password on the login screen
  • Click on the LOGIN button

KeyLib UI

You can find an example of the KeyLib user interface below, move your mouse to the info icons to find out more about the different parts and their function.

Activity: Creating a new Solution

  • Choose ‘New Solution’ in the File menu
  • Name the Solution ‘KeyLib CBT’
  • Click ‘Create’

The new Solution is now shown in the Solution Explorer.

Activity: Creating a new KeyFile

  • Right-Click on the Solution name
  • Choose ‘New KeyFile’
  • Name the KeyFile ‘Start Testform’
  • Click ‘Create’

The newly created KeyFile has now been added to the Solution and is visible in the Editor.

Example: Adding the START Keyword

The first step is starting the test application by using the keyword START. The video below illustrates how to use START in your KeyFile.

Activity: Using the START keyword

We begin by starting the test application.

  • Click on COMMENT in the KeyFile editor
  • Type the following in the text field next to the keyword:

Your KeyFile should look like the example in the image.

Activity: Running a test

  • Check the ‘Live’ box in the KeyLib menu bar. 

Doing this enables you to watch the test as it happens.

  • Start the Test by clicking on the ‘Run’ button in the KeyFile editor

The Live Window opens and the test application has started running.

Example: Using the Capture Tool

KeyLib knows where to execute the required actions by recognising images on your screen.

We use the Capture Tool to capture these images. The video below shows how capturing images works.

Activity: Capturing the KeyLib logo

  • Open the Capture Tool (Tools - Capture Tool)
  • Click on the button ‘Capture’
  • Scroll to the KeyLib logo in the window
  • Use the mouse to make a rectangular selection around the KeyLib logo
  • Click on “Save” and name the image “Logo”

Pro-tip: Always capture an image that is unique to the screen or screen element you want to use, and make the image as small as possible. This reduces the chance that software changes will affect the captured images.

Activity: Checking the saved image in the Object Editor

Check whether you saved the image correctly

  • Open the Object Editor (Tools - Object Editor)
  • Click on the captured image

If you captured the image correctly, it should look like the example image

Activity: Recovering the precondition

The correct screen and the correct information must be on screen before executing a test. We call this the precondition.

We have just started the application, now we are going to recover the precondition in order to execute the test again.

  • Activate the Live Window by clicking on the Live Window tab
  • Close the browser

Activity: Waiting for the test application

  • Add the WAIT keyword to your KeyFile.
  • Leave the “Seconds” field empty (this indicates that KeyLib should WAIT for a fixed amount of time)
  • Click on the Object field next to the WAIT keyword.
  • Select the captured image “Logo”

This indicates that KeyLib should wait until the image is on screen.

  • Start the test by clicking on the “Run” button in the KeyFile Editor

You can now see KeyLib waiting for the KeyLib logo to be found.

Important: Waiting

After every action that changes the screen, like starting an application or opening a window, it is important to wait until it is absolutely certain that the previous action has finished. 

This prevents KeyLib from continuing with the next step when the application is not ready.

Activity: Viewing the results of a test

The results of the executed steps are shown in the Results window during the execution of the test and afterwards.

  • Click on the Results tab below the KeyFile Editor. If the tab is not visible, click on View - Results in the KeyLib menu bar.
  • Click on the plus sign in front the green check mark. This shows the executed steps.

Since all steps have a green check mark, it means all steps have been executed successfully.

Question: Complete the following sentence: The START keyword starts an application on the KeyLib Client by

  • Selecting it from the list of applications
  • Double-clicking the icon of the program on the desktop
  • Typing the application path in the Windows Run dialog
  • Typing the application path in Windows Explorer

Question: How do you ensure that KeyLib does not carry out the steps in a KeyFile too quickly?

  • It is unnecessary, KeyLib never runs faster than the application that is being tested.
  • It is unnecessary, KeyLib looks at the screen with every keyword until the searched image appears.
  • You set a fixed waiting time per screen transition that is long enough to accommodate the changing response times of the application.
  • For every screen transition, you make KeyLib wait for an object that shows that the application is ready to continue.

Question: Why should your captured images be as small as possible?

  • Large images create performance issues for KeyLib
  • The smaller the image, the smaller the chance that it will have to be recaptured after changes to the application
  • KeyLib finds small images faster than large images
  • Small images take up less disk space. Especially when your test set increase in size, the required amount of disk space can increase significantly.

Example: Capturing a text field

The next activity will be practice for typing a name in an input field. The first step is capturing the input field with the Capture Tool, as shown in the video below.

Explanation: Hotspots

In the video on the previous page, the red circle or hotspot was dragged from the center of the selected rectangle into the text field.

We recognise the input field by the label above it, but the location of the action in KeyLib is indicated by the hotspot.

Activity: Entering your name into a text field

  • Open the capture Tool.
  • Select the text "Name".
  • Place the hotspot in the text field.
  • Save the picture under the name "fieldName".

Activity: Entering your name into a text field (2)

  • Create a new KeyFile with the name "Rent A Car" (hint: Right-click on the name of the Solution in the Solution Explorer).
  • Add the EDIT keyword to the KeyFile. The EDIT keyword inserts text into a text field.
  • Use the Object you have just captured as the Object in the EDIT step
  • Enter your own name under "Text to type"
  • Start the test by clicking on “Run" in the KeyFile editor.

KeyLib now enters your name into the text field.

Question: When is it necessary to move the hotspot of an image?

  • When the location of the action is not in the center of the searched text or image
  • Always move the hotspot, otherwise KeyLib might click on the wrong spot
  • The hotspot hardly ever has to be moved.
  • The hotspot only needs to be moved for the keyword Edit.

Activity: Entering an address

We will continue by typing an address into an address field.

  • Capture the address field with the capture Tool (in the same way you captured the text field before)
  • Add a new EDIT keyword directly underneath the first EDIT keyword
  • Enter the street name behind the EDIT keyword
  • Click on the field "Enter keycombinations here" and press the Return or Enter key (the Return key is added to the text)
  • Enter the postal code and house number behind the text {Return}
  • Run the test

The address information is now added into both text fields.

Activity: Choosing a different car

We will use KeyLib to search for both an image and text on screen.

  • Open the capture Tool
  • Select the text "Car type" and drag the hotspot to the drop-down list
  • Save the picture with the name "choiceCar"

Activity: Choosing a different car (2)

  • Add the keyword COMBOBOX from the list of keywords to your KeyFile

The keyword COMBOBOX opens drop-down list and selects a value.

  • Select the new object “choiceCar” as the Object for COMBOBOX
  • Enter the text “Volkswagen" in the text field behind COMBOBOX. 

Because you have not defined the text as an image, KeyLib will do a text search on screen.

  • Run the test

KeyLib now selects the correct car in the drop-down menu.

Activity: Choosing insurance type

  • Use the Capture Tool to capture an image of the "Passengers" insurance.
  • Add the keyword RADIOBUTTON to your KeyFile and Add the “Passengers” image as Object
  • Run the test

KeyLib now selects the chosen insurance.

Activity: Selecting options

  • Use the Capture Tool to capture the "Air Conditioning" and "Navigation System" options
  • Add the keyword CHECKBOX to your KeyFile twice to check these options
  • Run only the last two lines of the KeyFile by right-clicking on the first CHECKBOX line and selecting the option "Run from here"

KeyLib now checks both options.

Explanation: Scrolling

Sometimes you have to scroll to be able to fill in all the necessary information on screen. The keyword “SCROLL" allows KeyLib to scroll to the object you want to use.

To ensure that you scroll in the right window, we first put the mouse cursor in the right place. Play the video below to see how it works.

Activity: Scrolling down

  • Use the capture Tool to capture images of the cursor position and the text “Upload ID”
  • Scroll back up in the Live Window after capturing the “Upload ID” text
  • Add the keyword Scroll to your KeyFile
  • Choose direction "Down" in the first field
  • Add the "Upload ID" image to the "Object to scroll" field
  • Enter the image of the cursor position in the Cursor position field,
  • Run the test twice from the last line in the KeyFile (Use “Run from here”)

KeyLib scrolls down twice, until the text "Upload ID" is displayed. There is no scrolling action the second time because the text is already on screen.

Pro-tip: Scrolling only works if the mouse cursor is on the screen in which you want to scroll. If the Scroll keyword does not seem to work, then the mouse cursor is probably not in the right place. To solve this, select an object in the field "Cursor position". The mouse cursor is then placed in the hotspot of this object before any scrolling action.

Question: What is the purpose of the cursor position when scrolling?

  • It ensures that the mouse is not in the place where the image has to be found
  • It places the mouse in the correct window for scrolling
  • It ensures that KeyLib does not scroll past the image it is searching for
  • It prevents the scroll action when the image KeyLib is looking for is already on screen

Activity: Entering a rental period

The bottom of the form displays a text field where you can enter a rental period in days

  • In the "Days" field, enter the value 3 (capture the text field with the Capture Tool first)
  • Use Tab key to finish entering the number (hint: use the field "Enter keycombinations here" to add the Tab key)
  • Only run this last step 

You now see that KeyLib enters the value 3 in the text field and that the value 210 is shown to be the total amount.

Explain: Restoring the precondition

So far we have restored the precondition via the Live Window when it was necessary (closing an application, scrolling back up).

We are now going to automatically restore the precondition of a test. For this we will change the KeyFile  that starts the test application.

Explanation: IF keyword

To restore the preconditions, we should first check whether the test application is already running. For this purpose KeyLib uses the IF keyword. If the test application is running, you can close the application by typing Alt + F4 and wait until the application is closed (when KeyLib logo is no longer visible on the screen).

The test application is then restarted. The video below illustrates this process.

Activity: Adjusting the startup KeyFile

  • Open the KeyFile "Start Testform" by double-clicking on it in the Solution Explorer
  • Drag the IF keyword from the keywords list to the top of the KeyFile
  • Select the KeyLib logo as Object
  • Add the TYPE keyword your KeyFile by dragging It to the IF step in your KeyFile
  • Click on the plus sign in front of IF
  • Select the "Text to type" field behind the TYPE keyword and press Alt + F4 on your keyboard
  • Add the VALIDATE keyword from the keywords list to the IF step in your KeyFile
  • Select the KeyLib logo as object for VALIDATE and choose "Not Exists" in the field behind it
  • Run the test.

KeyLib wil now restart the test application.

Pro-tip: To make sure that you do not restart the test application too soon, have KeyLib wait until the KeyLib logo is no longer visible. To wait for something to disappear from the screen, we use VALIDATE with the "NotExists" option.

Explanation: Shared KeyFiles

The startup KeyFile is a building block that restores the precondition.

To be able to use it in other KeyFile we make this building block shared.

You do this by clicking with the right mouse button on the name of the KeyFile and select "Is Shared" in the popup menu.

Activity: Adding a Shared Script to a KeyFile

  • Right-click on the KeyFile "Start Testform"
  • Select the option "Is Shared"

The icon in front of the KeyFile changed into a share icon. This indicates that his KeyFile can now be used in other KeyFiles.

  • Activate the KeyFile "Rent A Car"
  • Drag the KeyFile "Start Testform" from the Solution Explorer to the top of the “Rent A Car” KeyFile
  • Run the test

KeyLib now closes and restarts the application before running the test.

Question: When should you restore the precondition of a test?

  • When the test application no longer has the expected content on screen
  • When the test application is left in an unknown state due to the failure of a previous test
  • When certain fields are no longer visible due to scrolling in a window
  • It is recommended to always restore the precondition before running a test

Activity: Creating a data file

To check whether the field with the total amount contains the correct value, we will retrieve the value of this field.

KeyLib stores data received from an application in a data file.

  • Right-click on the text "Datafiles" below the Solution Explorer
  • Select "New datafile"
  • Name the data file "CBT data"

The data file is added and opened in the editor.

Activity: Adding a variable to a data file

A data file contains variables. A variable is a memory location with a name that allows you to store a value.

Variables in KeyLib always start with an at-sign (@).

  • Click on the first cell in the data-editor and enter @Total in the field.
  • Save your datafile by clicking on the "Save" button

You have now created a variable with the name @Total. 

The value of the variable can be entered in the second column. You can leave this empty for now.

Activity: Linking the data file to your KeyFile

  • Link the data file to KeyFile "Rent A Car" by right clicking on the KeyFile and choose "Data file"-"Select" in the popup menu
  • In the "Select a datafile" dialog, choose the "CBT Data" data file and click "Select"

You can now use the variables in the data file in your KeyFile.

Activity: Reading the total amount

  • Activate the KeyFile "Rent A Car".
  • Create a new object with the Capture tool by selecting the text "Rental price" with the hotspot in the field with the total amount
  • Add the READ keyword to your KeyFile
  • For the object field select the newly created object
  • Type in the veld "Variabele" the name of the variable from the data file (@Total)
  • Only executed that final step in the KeyFile

The variable in your data file now contains the value from the Total field.

Pro tip: Variable names are case-sensitive. Typos will show immediately after running the test. You will receive an error message stating that the variable does not exist, or the variable name is entered in the value field instead of a number.

Activity: Using VALIDATE to check values

  • Add the keyword VALIDATE to your KeyFile
  • Enter the variable @Total into the first field
  • Choose “Equals" in the drop-down list behind the first field
  • Enter the value 210 in the third field
  • Run the last step of your KeyFile

KeyLib now checks that the variable contains the correct value.

Activity: Confirming the reservation

As you have seen with the COMBOBOX keyword, KeyLib can also recognize text. Text recognition will be used to click on the “Reserve” button.

  • Add the keyword MOUSE to your script

The first two fields behind the MOUSE keyword are already correct (CLICK and LEFT).

  • Enter the text “Reserve” in the Object field

Activity: Confirming the reservation (2)

After clicking on the reservation button, the test application shows a different page on which the entered data can be checked.

  • Use the keyword WAIT and wait for the text "Check Page"
  • Run the last two steps in the KeyFile

Important: Similar to starting the test application, it is very important to wait until the previous action has finished. This activity illustraties this by waiting for the Check Page.

Activity: Analysing results

The results windows shows a red cross in front of the last test run. Something went wrong.

  • Expand the results for the last test

The message “Object was not found” indicates that KeyLib did not find the “Check Page” text.

  • Double-Click on the last line in the Results window

A new window opens with more information about the error.

Explanation: Detailed information about errors

The detailed error window shows a screen shot of the KeyLib Client and which error has occurred. The “Check Page" was not visible on screen during the test. 

It took too long for the right page to show up on screen, since by default KeyLib only searches for an object or text for 15 seconds. The test step failed because the object was not found within this timeframe.

Activity: Adjusting the Timeout property

Adjusting KeyLib’s wait time is done by adjusting the “Timeout” property in the Properties window.

Because loading the control page takes more than 15 seconds, the Timeout property needs to be adjusted.

  • Click on the last step in your KeyFile
  • Change the value of the Timeout property in the Properties window to 25 seconds (at the bottom right of the KeyLib screen)
  • If the Properties window is not visible, select "View" - "Properties" in the KeyLib menu

Activity: Returning to input screen

The validation page has loaded, so to be able to run the test again we should return to the input screen.

  • Add a step to your KeyFile that clicks on the "Correct data" button

This ensures that the test application goes back to the input page. 

To repeat, it is important to wait until the input screen is loaded.

  • Add a step to your KeyFile so KeyLib will WAIT for the input page
  • Run the last two steps of your KeyFile

The test application now shows the input screen again.

Activity: Testing the adjusted Timeout

  • Run the last 4 steps of your KeyFile

KeyLib will now show the Check Page and then go back to the input screen.

Question: How do you analyze errors?

  • By double-clicking on the failed step in the Results window a screen shot and detailed information are displayed.
  • By carrying out the test in its entirety again and observing the test in the Live window.
  • Both ways can help you to analyze an error.

Activity: Restarting the test application

  • Open the KeyFile "Start Testform"
  • Right-click on IF and select "Run selected"

The steps in IF are now run and the test application is closed.

  • Now run the entire KeyFile by clicking on the Run button in the editor

KeyLib restarts the test application. Running the IF section now takes a long time since KeyLib will search for the logo for 15 seconds, but will be unable to find it on screen.

Activity: Adjusting Timeout for IF

To check whether the test application has already started, KeyLib does not need to wait 15 seconds. The KeyLib logo is either visible or not visible on screen.

  • Select the "Start Testform" KeyFile
  • Click on IF in the KeyFile
  • In the Properties window, set the Timeout value to 1
  • Close the test application via the Live Window
  • Run the entire KeyFile

You can now see that starting up the test application is much faster.

Activity: Adding variables for name, address and number of days

You can also use variables to enter data into the application.

This allows you to enter and check different data with the same KeyFile without having to adjust the KeyFile.

  • Create 3 new variables in your datafile
  • Enter the values in the second column as illustrated on the right

Don't forget to save your datafile!

Activity: Replacing text in your KeyFile with variables

  • Activate the KeyFile "Rent A Car"
  • Replace the text at the first EDIT keyword with @Name
  • Replace the text used in the second EDIT keyword with @Address
  • Replace the "3" at the third EDIT keyword by @Days and make sure that the text {Tab} remains
  • Run the KeyFile

KeyLib now enters the content of the variables into the text fields.

Activity: Adding a variable to validate value

Changing the rental period to 4 days also changes the total cost. Add a new variable to check the value.

  • Add the variable @Check to the data file with value 280
  • Change the value of the variable @Days to 4
  • Use the variable @Check in the existing VALIDATE keyword
  • Run the last 7 steps in the KeyFile (from the last EDIT keyword)

Question: What could be the cause of the variable name being inserted in your data file instead of a numeric value?

  • There was a typo in the variable name
  • The variable does not exist
  • The data file is not linked to the KeyFile
  • All the above are possible


You have completed the KeyLib Foundation training. You can now work independently with KeyLib to set up KeyFiles and automate tests and processes.

Before getting started, we have a few KeyLib tips for you:

  • Always use the WAIT keyword when the screen changes. This ensures that KeyLib does not go faster than the application can handle.
  • If you have used WAIT everywhere between screen transitions and errors still occur, increase the default Timeout value. You do this by clicking on the Solution name in the Solution Explorer and increasing the Timeout value in the properties window.
  • Capture unique images in the Capture Tool, but make them as small as possible. This reduces the chance that you will have to re-capture images if the application changes.
  • Use shared scripts at the beginning of each test to restore the preconditions. This ensures that your test always starts in the same place.

For a complete overview of all KeyLib functionality, read the Manual as well as the Keywords and Functions document. If you have any questions, have a look at the FAQ on Send an email to [email protected] to gain access to the support portal.