aqObject.CompareProperty Method

Applies to TestComplete 14.30, last modified on November 21, 2019

Description

The aqObject.CompareProperty method allows you to perform a property checkpoint from script code, that is, to verify an object’s property value according to a certain condition. If the verification succeeds, the method posts a success message to the test log; otherwise it posts a failure message.

The method can test properties that have simple value types (string, number, boolean and so on) and does not support properties that contain complex values such as arrays, objects and alike. If test properties have different value types, TestComplete will try to convert the object property value to the type of the expected value and then perform verification.

Note: If an object has a property or method that returns a DISPID_VALUE (for information on this, see DISPID Constants in the MSDN Library), the object is considered to have a value of a simple type and can be used for property validation. For example, a JavaScript array of simple values is an object with a string value (comma-separated list of items) and a .NET string is an object with a property returning the string contents.

Note that instead of using the aqObject.CompareProperty method, you can compare property values with expected values using the appropriate scripting language operators: =, >, >=, <, <= and so on. Using the aqObject.CompareProperty method makes sense if you need to perform complex string comparisons like "contains", "starts with" and so on, with or without letter case taken into account.

Declaration

aqObject.CompareProperty(Property, Condition, Value, CaseSensitive, MessageType)

Property [in]    Required    Variant    
Condition [in]    Required    Integer    
Value [in]    Required    Variant    
CaseSensitive [in]    Optional    Boolean Default value: True   
MessageType [in]    Optional    Integer Default value: lmWarning   
Result Boolean

Applies To

The method is applied to the following object:

aqObject

Parameters

The method has the following parameters:

Property

The property value to be checked. For example, Sys.Clipboard. This value must be of a simple (non-object) type: string, number, boolean and so on.

Condition

One of the following constants that specifies the property value test condition:

Constant Value Description
cmpEqual 0 Check whether the Property value equals to Value.
cmpNotEqual 1 Check whether the Property value is not equal to Value.
cmpGreater 2 Check whether the Property value is greater than Value.
cmpLess 3 Check whether the Property value is less than Value.
cmpGreaterOrEqual 4 Check whether the Property value is greater or equal to Value.
cmpLessOrEqual 5 Check whether the Property value is less or equal to Value.
cmpContains 6 Check whether the Property value contains Value.
cmpNotContains 7 Check whether the Property value does not contain Value.
cmpStartsWith 8 Check whether the Property value starts with Value.
cmpNotStartsWith 9 Check whether the Property value does not start with Value.
cmpEndsWith 10 Check whether the Property value ends with Value.
cmpNotEndsWith 11 Check whether the Property value does not end with Value.
cmpMatches 12 Check whether the Property value matches the regular expression specified by Value.
cmpNotMatches 13 Check whether the Property value does not match the regular expression specified by Value.
cmpIn 14 Check if Value contains the Property value. (Similar to cmpContains, but the other way round.)
cmpNotIn 15 Check if Value does not contain the Property value. (Similar to cmpNotContains, but the other way round.)

When testing a property value of a string type, you can use any of these conditions. For more information about string comparison rules, see the Remarks section.

When testing a numeric property value, you can use any of the following conditions: cmpEqual, cmpNotEqual, cmpGreater, cmpLess, cmpGreaterOrEqual, cmpLessOrEqual.

When testing a property that has a boolean value, you can only use the cmpEqual or cmpNotEqual condition.

Value

Specifies the value to test the property value against. The meaning of this parameter depends on the Condition parameter (see the table above).

CaseSensitive

If Property and Value are strings, this parameter specifies whether the should perform case-sensitive or case-insensitive comparison; otherwise, this parameter is ignored. By default, this parameter is True, which means case-sensitive comparison; False means that the letter case is ignored.

MessageType

If the property verification fails, the posts a message to the test log. This parameter specifies the message type. It can be one of the following constants:

Constant Value Description
lmNone 0 Do not post any message.
lmMessage 1 Post an informative message.
lmWarning 2 Post a warning message.
lmError 3 Post an error message.

Result Value

True if the property value matches the specified condition and False otherwise.

Remarks

  • String comparisons ("equals to", "greater than", "less than" and similar) use character codes and are not affected by the locale. For example, "b" is greater than "a", "c" is greater than "b" and so on. If the CaseSensitive parameter is True, letter case is taken into account ("a" is greater than "A"), otherwise it is ignored ("a" is equal to "A"). The comparison is performed symbol-by-symbol and finishes once a difference is found or when both strings have been compared to the end. If two strings having different lengths compare as equal to the end of one string, the longer string is considered as the greater one. For instance, "abcd" is greater than "ab".

  • To verify an object property's value, you can also use the CheckProperty method.

  • You can use the cmpIn, cmpNotIn, cmpContains and cmpNoteContains conditions to test a value against comma-separated, pipe-separated lists, and so on, that is, to check whether the value equals (or does not equal) to any value stored on the list. For example, you can use the cmpIn condition to check whether the value of the Sys.OSInfo.Name property that contains the name of the currently running operating system belongs to the comma-separated list "Win7,WinVista,Win2008":

    JavaScript, JScript
    Python
    VBScript
    DelphiScript
    C++Script, C#Script

    JavaScript, JScript

    aqObject.CompareProperty(Sys.OSInfo.Name, cmpIn, "Win7,WinVista,Win2008");

    Python

    aqObject.CompareProperty(Sys.OSInfo.Name, cmpIn, "Win7,WinVista,Win2008")

    VBScript

    Call aqObject.CompareProperty(Sys.OSInfo.Name, cmpIn, "Win7,WinVista,Win2008")

    DelphiScript

    aqObject.CompareProperty(Sys.OSInfo.Name, cmpIn, 'Win7,WinVista,Win2008');

    C++Script, C#Script

    aqObject["CompareProperty"](Sys["OSInfo"]["Name"], cmpIn, "Win7,WinVista,Win2008");

Example

The following example demonstrates how you can perform various verifications of a string value:

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script

JavaScript, JScript

function ComparePropertySample()
{
  var str = "abracadabra";

  // False - letter case is different
  Log.Message( aqObject.CompareProperty(str, cmpEqual, "ABRACADABRA", true) );

  // True - letter case is ignored
  Log.Message( aqObject.CompareProperty(str, cmpEqual, "ABRACADABRA", false) );

  // True
  Log.Message( aqObject.CompareProperty(str, cmpContains, "a") );

  // False - letter case is different
  Log.Message( aqObject.CompareProperty(str, cmpStartsWith, "ABRA", true) );

  // True - letter case is ignored
  Log.Message( aqObject.CompareProperty(str, cmpEndsWith, "CADABRA", false) );
}

Python

def ComparePropertySample():
  str = "abracadabra"
  # False - letter case is different
  Log.Message(aqObject.CompareProperty(str, cmpEqual, "ABRACADABRA", True))
  # True - letter case is ignored
  Log.Message(aqObject.CompareProperty(str, cmpEqual, "ABRACADABRA", False))
  # True
  Log.Message(aqObject.CompareProperty(str, cmpContains, "a"))
  # False - letter case is different
  Log.Message(aqObject.CompareProperty(str, cmpStartsWith, "ABRA", True))
  # True - letter case is ignored
  Log.Message(aqObject.CompareProperty(str, cmpEndsWith, "CADABRA", False))

VBScript

Sub ComparePropertySample
  Dim str
  str = "abracadabra"

  ' False - letter case is different
  Log.Message aqObject.CompareProperty(str, cmpEqual, "ABRACADABRA", True)

  ' True - letter case is ignored
  Log.Message aqObject.CompareProperty(str, cmpEqual, "ABRACADABRA", False)

  ' True
  Log.Message aqObject.CompareProperty(str, cmpContains, "a")

  ' False - letter case is different
  Log.Message aqObject.CompareProperty(str, cmpStartsWith, "ABRA", True)

  ' True - letter case is ignored
  Log.Message aqObject.CompareProperty(str, cmpEndsWith, "CADABRA", False)
End Sub

DelphiScript

procedure ComparePropertySample;
var str;
begin
  str := 'abracadabra';

  // False - letter case is different
  Log.Message( aqObject.CompareProperty(str, cmpEqual, 'ABRACADABRA', true) );

  // True - letter case is ignored
  Log.Message( aqObject.CompareProperty(str, cmpEqual, 'ABRACADABRA', false) );

  // True
  Log.Message( aqObject.CompareProperty(str, cmpContains, 'a') );

  // False - letter case is different
  Log.Message( aqObject.CompareProperty(str, cmpStartsWith, 'ABRA', true) );

  // True - letter case is ignored
  Log.Message( aqObject.CompareProperty(str, cmpEndsWith, 'CADABRA', false) );
end;

C++Script, C#Script

function ComparePropertySample()
{
  var str = "abracadabra";

  // False - letter case is different
  Log["Message"]( aqObject["CompareProperty"](str, cmpEqual, "ABRACADABRA", true) );

  // True - letter case is ignored
  Log["Message"]( aqObject["CompareProperty"](str, cmpEqual, "ABRACADABRA", false) );

  // True
  Log["Message"]( aqObject["CompareProperty"](str, cmpContains, "a") );

  // False - letter case is different
  Log["Message"]( aqObject["CompareProperty"](str, cmpStartsWith, "ABRA", true) );

  // True - letter case is ignored
  Log["Message"]( aqObject["CompareProperty"](str, cmpEndsWith, "CADABRA", false) );
}

See Also

About Property Checkpoints
Alternatives to Property Checkpoints

Highlight search results