Call calls another unit, returning to this unit after the call.

call unitname [with ...]

unitname is either

• An absolute unit name in dotted notation
• A relative unit name, in the same package as the current test, with no dots in the name

Refer with→ UnitName→

Parameter Names

Relative names are added to the Context CallParams→ map with the given relative name.

Absolute names are added to a virtual context such that they are downward visible only.

Parameter pass-through with %BaseParams%

It is sometimes necessary for a test unit to pass through all the call parameters that it receives to another (target) test unit. This can happen for example when a test unit piggybacks on another (target) test unit whose parameter are named the same. Passing parameters through is a way to remove unnecessary duplication, and enforces the use of the exact same parameter names in all test units on the way to the target test unit.

call ... with
    %BaseParams% %CallParams%
end

Note that this can also be used to call the same function is various locations with a common set of parameters: you can extract the common parameters, use that as the base, and add any extra parameters required to the call.

Optional parameters

Consider the following in a test case:

call ... with
    %Param% %Value%
end

If %Value% does not exist, an error will occur. Sometimes, this is not what we want, as in this example from Compose:

call unit.web.UpdateForm with
  %Name% message-compose-form
  
  %Params% with
    %sbj% %Cmds:Subject%
    %msg_name%  %Cmds:Name%    
    %msg_body_plain%  %Cmds:BodyText%
    %msg_body_html% %Cmds:BodyHTML%
    ...
  end
end

If %Cmds:BodyText% does not exist then the parameter should simply not be set in the form, it should not be added to the %Params% map. This is achieved using the optional keyword:

call unit.web.UpdateForm with
  %Name% message-compose-form
  
  %Params% with
    %sbj% %Cmds:Subject%
    %msg_name% optional %Cmds:Name%    
    %msg_body_plain% optional %Cmds:BodyText%
    %msg_body_html% optional %Cmds:BodyHTML%
    ...
  end
end

Expanded Unit Name

Note that unitname is subject to normal standard rvalue expansion→, and as such the actual unit called may be constructed at run time.

Refer to <test_call_expandname.test>

Relative Name Caveat

A relative name will be relative to the caller only (this apples also in the Java code). This is important to note because if you pass the name to a function, such as exec→, the call will end up be relative to the *CalledFunction* and not the caller of the function. In such cases you need to use the absolute unit name.