How to: Create Handler Functions

You can create test codeunits, test functions, and test pages to test your application. We recommend that you create tests that can be automated. To create automated tests, you must write code to handle all UI interactions so that the tests do not require user interaction when they are running. To do this, you create special handler functions.

You can use the following handler functions:

• MessageHandler

• ConfirmHandler

• StrMenuHandler

• PageHandler

• ModalPageHandler

• ReportHandler

• RequestPageHandler

Note

If you create a ReportHandler function, then that function replaces all code for running the report, including the request page, and a RequestPageHandler is not called. Only create a RequestPageHandler if you are not using a ReportHandler.

Before you begin, you must create a test codeunit and test function. For more information, see How to: Create Test Codeunits and Test Functions.

To create a handler function

1. In the development environment, on the Tools menu, choose Object Designer.

2. In Object Designer, choose Codeunit, select your test codeunit, and then choose Design.

3. On the View menu, choose C/AL Globals.

4. In the C/AL Globals window, on the Functions tab, enter the name of the new handler function.

5. On the View menu, choose Properties.

6. In the Properties window, in the FunctionType property, select the type of handler from the drop-down list.

7. In the C/AL Globals window, on the Functions tab, choose Locals to specify the signature of the handler functions. The following table describes the signature that is required for each type of handler function.

   FunctionType	Signature
   MessageHandler	<Function name>(<Msg> : Text[1024])
   ConfirmHandler	<Function name>(<Question> : Text[1024]; VAR <Reply> : Boolean)
   StrMenuHandler	<Function name>(<Options : Test[1024]; VAR <Choice> : Integer; <Instruction> : Text[1024])
   PageHandler	<Function name>(VAR <variable name> : Page <page id>) <Function name>(VAR <variable name> : TestPage <testpage id>)
   ModalPageHandler	<Function name>(VAR <variable name> : Page <page id>; VAR <Response> : Action) <Function name>(VAR <variable name> : Page <testpage id>)
   ReportHandler	<Function name>(VAR <report name> : Report <report id>)
   RequestPageHandler	<Function name>(VAR <TestRequestPage > : TestRequestPage)

   The parameters of the functions that are being handled are passed as parameters to the handler functions. For example, when MESSAGE is called in a test function, the parameter of the MESSAGE function is passed as the parameter of the MessageHandler function. For page and report handlers, the page, report, or request page is passed as the parameter of the PageHandler, ModalPageHandler, ReportHandler, or RequestPageHandler.

   Parameters that are specified as VAR are passed by reference to the handler function. The value of the parameter can be changed by the handler function.

   For example, to specify the signature for a ConfirmHandler function, do the following:

   1. In the C/AL Locals window, on the Parameters tab, enter a name for the <Question> parameter. In the DataType field, select Text. In the Length field, enter 1024. Verify that the Subtype field is blank.

   2. Enter a name for the <Reply> parameter. In the Var field, select the check box. In the DataType field, select Boolean. Verify that the Subtype and Length fields are blank.

   3. In the code of the ConfirmHandler function, set the reply that you want to simulate by setting the value of the Reply parameter.

8. In the C/AL Globals window, select the test function that requires a handler function. For example, a test function that requires a handler function calls some application code, which then calls the CONFIRM function.

9. On the View menu, choose Properties.

10. In the Properties window for the test function, in the HandlerFunctions property, enter the name of the handler function that this test function will use instead of the UI. For example, if the code tested by this test function calls the CONFIRM function, then enter the name of your ConfirmHandler function. To specify more than one handler function, separate the handler function names with a comma.

    Note

    Every handler function that you enter in the HandlerFunctions property of a test function must be called at least one time in the test function. If you run a test function that has a handler function listed that is not called, then the test fails.

11. In the C/AL Editor, enter code for the handler functions that you defined. The code should simulate in the code that is being tested that the UI was actually raised and some values entered or some actions were taken. For example, the code could verify that the expected text is presented. The code should exit with the same state with which the UI would exit.

12. On the File menu, choose Save.

13. In the Save window, verify that the Compiled check box is selected, and then choose the OK button to save and compile the test codeunit.

See Also

Tasks

How to: Create Test Codeunits and Test Functions
How to: Create a Test Runner Codeunit

Concepts

Testing the Application