TestComplete EngineComponentCommands

Last Updated:

Engine commands for components.

These commands are generally for interrogating engines about the Windows and Components they can find. These are not normally used during testing. (But they can be used during testing like any other command record.)

For example, these commands are heavily used by STAFProcessContainer during test design time.

Each engine command has different parameters as described in its documentation. For reference, the first fields of ALL Engine Command test records are defined below:

Field #1 -- "E" = ENGINE COMMAND record type specifier.

Field #2 -- The Engine Command keyword.

Example:

E, GetTopLevelWindows

Engine Command parameters must be placed in the test record in the field position specified in the documentation. Some parameters are optional. However, the field associated with that parameter must be honored. If you wish to skip an optional parameter you must still provide an empty field for that parameter.

Example:

E, SomeCommand, Value1, Value2, , , Value5

The above example shows two optional fields after Value2 which are given no value(skipped).

Engine commands that return a value do so in the SAFS/Hook/statusinfo variable of SAFSVARS which is populated via TestRecordData.statusinfo.

The Android Engine also persists these values as SAFS variables. 

            ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

See DEngineCommandProcessor.setStatusVars().

The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

            
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.FullName   = [object.FullName] -- the TestObjects.FullName string--if command returns only 1 reference.
            ^TCAFS.UID.Count  = [Number of UID References created last]
            ^TCAFS.UID.1      = [First UID Reference created]
            ^TCAFS.UID.n      = [UID Reference number n]

The TestRecordData.statuscode is set to NO_SCRIPT_FAILURE if the engine supports and processes the command. This is true even if the command results in an empty, missing, or null return value.

SCRIPT_NOT_EXECUTED should be returned in TestRecordData.statuscode if the engine does not support the command.

Note that the full availablility of all Engine Commands may be spread across several files. Together, all of these files define all the Engine Commands available to the core framework.



[How To Read This Reference]
ClearReferenceCache
TC
Clear the Object reference cache used in a remote engine.
GetCurrentWindow
TC
Return a reference to the top-most active (Window) with focus.
GetTopLevelCount
TC
Get the number of visible top-level items (Windows?) for the engine.
GetTopLevelWindows
TC
Return references to all known top-level items (Windows).
IsEnabled
TC
Is the component Enabled (vs. disabled)?
IsShowing
TC
Is the component visible?
IsTopLevelPopupContainer
TC
Is the component a top-level Popup Container?
IsValid
TC
Does the component still exist as a valid object?
SetActiveWindow
TC
Make the component the active (topmost?) Window or Component.

TestComplete EngineComponentCommands::ClearReferenceCache
TC

Clear the Object reference cache used in a remote engine.

Clear the Object reference cache used in a remote engine. When a driver or controller requests a unique reference for a remote Object the Object and a String Key are stored in an internal cache in the remote engine. This command instructs the remote engine to clear its internal cache of Objects and Keys.

Fields: [ ]=Optional with Default Value
    Examples:
    [How To Read This Reference]

    TestComplete EngineComponentCommands::GetCurrentWindow
    TC

    Return a reference to the top-most active (Window) with focus.

    The Android Engine also persists these values as SAFS variables. 

                ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

    See DEngineCommandProcessor.setStatusVars().

    The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.FullName   = [object.FullName] -- the TestObjects.FullName string--if command returns only 1 reference.
            ^TCAFS.UID.Count  = [Number of UID References created last]
            ^TCAFS.UID.1      = [First UID Reference created]


    Fields: [ ]=Optional with Default Value
      Examples:
      [How To Read This Reference]

      TestComplete EngineComponentCommands::GetTopLevelCount
      TC

      Get the number of visible top-level items (Windows?) for the engine.

      Returns the number of visible top-level items, or 0. Not all engines can see all items. For example, Selenium only looks for Web clients. Some engines may only look for Java clients, etc.. Some engines can see other top-level items that are not Windows--like Processes, or Threads, etc...

      The Android Engine also persists these values as SAFS variables. 

                  ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

      See DEngineCommandProcessor.setStatusVars().

      The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                  
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]


      Fields: [ ]=Optional with Default Value
        Examples:
        [How To Read This Reference]

        TestComplete EngineComponentCommands::GetTopLevelWindows
        TC

        Return references to all known top-level items (Windows).

        The engine can only return references to those top-level items it has knowledge of. Not all engines can see all items. For example, Selenium only looks for Web clients. Some engines may only look for Java clients, etc.. Some engines can see other top-level items that are not Windows--like Processes, or Threads, etc...

        The engine's array of objects will be returned as a delimited list of fields. The first character in the String will identify the separator used between each reference. If no top level windows were found then the engine will return an empty string.

        The Android Engine also persists these values as SAFS variables. 

                    ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

        See DEngineCommandProcessor.setStatusVars().

        The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                    
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.UID.Count  = [Number of UID References created last]
            ^TCAFS.UID.1      = [First UID Reference created]
            ^TCAFS.UID.n      = [UID Reference number n]


        Fields: [ ]=Optional with Default Value
          Examples:
          [How To Read This Reference]

          TestComplete EngineComponentCommands::IsEnabled
          TC

          Is the component Enabled (vs. disabled)?

          Should return text "true" if the component is Enabled. Return text "false" if it is not.

          The Android Engine also persists these values as SAFS variables. 

                      ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

          See DEngineCommandProcessor.setStatusVars().

          The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                      
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.FullName   = [object.FullName] -- the TestObjects.FullName string--if command returns only 1 reference.


          Fields: [ ]=Optional with Default Value
          1. Component
            An object reference or proxy reference to the component.

            A reference to a particular component previously returned from a call to getTopLevelWindows, getChildren, or one of the other engine commands that return such references.

          Examples:
          [How To Read This Reference]

          TestComplete EngineComponentCommands::IsShowing
          TC

          Is the component visible?

          Returns text "true" if the component is set to be visible. Returns text "false" if the component is set to be hidden or otherwise is not visible.

          The Android Engine also persists these values as SAFS variables. 

                      ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

          See DEngineCommandProcessor.setStatusVars().

          The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                      
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.FullName   = [object.FullName] -- the TestObjects.FullName string--if command returns only 1 reference.


          Fields: [ ]=Optional with Default Value
          1. Component
            An object reference or proxy reference to the component.

            A reference to a particular component previously returned from a call to getTopLevelWindows, getChildren, or one of the other engine commands that return such references.

          Examples:
          [How To Read This Reference]

          TestComplete EngineComponentCommands::IsTopLevelPopupContainer
          TC

          Is the component a top-level Popup Container?

          Should return text "true" if the component is. Return text "false" if it is not. Different domains or environs will have different classes or types that are Popup Windows or Popup containers.

          The Android Engine also persists these values as SAFS variables. 

                      ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

          See DEngineCommandProcessor.setStatusVars().

          The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                      
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.FullName   = [object.FullName] -- the TestObjects.FullName string--if command returns only 1 reference.


          Fields: [ ]=Optional with Default Value
          1. Component
            An object reference or proxy reference to the component.

            A reference to a particular component previously returned from a call to getTopLevelWindows, getChildren, or one of the other engine commands that return such references.

          Examples:
          [How To Read This Reference]

          TestComplete EngineComponentCommands::IsValid
          TC

          Does the component still exist as a valid object?

          Should return text "true" if the component is still valid. Return text "false" if it is not.

          The Android Engine also persists these values as SAFS variables. 

                      ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

          See DEngineCommandProcessor.setStatusVars().

          The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                      
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.FullName   = [object.FullName] -- the TestObjects.FullName string--if command returns only 1 reference.


          Fields: [ ]=Optional with Default Value
          1. Component
            An object reference or proxy reference to the component.

            A reference to a particular component previously returned from a call to getTopLevelWindows, getChildren, or one of the other engine commands that return such references.

          Examples:
          [How To Read This Reference]

          TestComplete EngineComponentCommands::SetActiveWindow
          TC

          Make the component the active (topmost?) Window or Component.

          Normally, this is only valid for window or child window components. There is currently nothing defined to be returned by this command.

          The Android Engine also persists these values as SAFS variables. 

                      ^DroidEngine.Command    = [command]
            ^DroidEngine.StatusCode = [statuscode string]
            ^DroidEngine.StatusInfo = [statusinfo]

          See DEngineCommandProcessor.setStatusVars().

          The TestComplete Engine (TCAFS) also persists these values as SAFS variables. 

                      
            ^TCAFS.Command    = [command]
            ^TCAFS.StatusCode = [statuscode string]
            ^TCAFS.StatusInfo = [statusinfo]
            ^TCAFS.FullName   = [object.FullName] -- the TestObjects.FullName string--if command returns only 1 reference.


          Fields: [ ]=Optional with Default Value
          1. Component
            An object reference or proxy reference to the component.

            A reference to a particular component previously returned from a call to getTopLevelWindows, getChildren, or one of the other engine commands that return such references.

          Examples:
          [How To Read This Reference]