Custom String Generator Rules

Applies to TestComplete 14.93, last modified on September 16, 2021

This topic contains information on specifying the formatting string for the Custom String generator. The topic includes the following information:

Basic Concepts

To describe the format of text data that the custom string generator produces, you use a string containing a combination of special macros, string literals and regular expressions. Below is a sample formatting string that can be specified in the generator parameters:

Sample Custom String

This sample string contains the following parts:

  • Macros. The macro names start with the % characters and typically have parentheses. Macros generate data of the needed data type and insert it into the resulting string. Macros can have parameters. For more information about macros, see below.

  • Regular expressions. They help you generate and insert random sequences of characters into the generated string. For information on supported regular expressions, see Custom-String Generator - Supported Regular Expressions.

  • String literals. You use them to specify symbols that should be literally included into the resulting string.

Note: The regular expressions are used only if the Use regular expressions parameter of the custom string generator is enabled. If this parameter is disabled, TestComplete treats regular expression parts as string literals.

Important: If you use regular expressions and you need special characters (brackets, parentheses, periods, and others) to be treated literally, precede them with backslashes (“\”). See below.

Here are some examples of formatting strings:

  • %INT(1,100,1)\. %NAME(MALE,FULL) from %CITY \(id:[a-z]{5}[1-9]+\)

    Generates a string that includes an integer number, male name, city and ID. The ID is generated with a regular expressions. Note that we escape the period and parentheses with backslashes.

    Sample output:

    1. Ali Duke from Geneva (id:oegkb85)
    2. Carson Garrett from Vail (id:pdwjn768)
    3. Mannix Clarke from Beacon (id:sdnwk3)
    ...

  • %COMP(IPv4) \(%SET(Armstrong, AT&T, Mediacom)\)

    Generates a list of IP addresses and Internet provider names. Note that we escape parentheses.

    Sample output:

    233.49.31.4 (Armstrong)
    44.40.24.39 (AT&T)
    18.15.164.107 (Mediacom)
    ...

Macros

  • You use macros to insert generated data of various types into the string that the custom string generator produces.
  • Macro names match the appropriate generators, for instance, %INT means the Integer number generator, %NAME - Human name generator, and %COMP - the Computer Address generator. For information on available macro names, see macro descriptions.

  • Some macros can have parameters. They are specified in parentheses. If the macro has no parameters, or if your skip all the parameters, you can also skip the parentheses.

    The parameters are separated by commas. The spaces between parameters are ignored.

    For some macros the parameter order is critical, for others - it is not.

    For information on parameters available for this or that macro, see the macro description.

  • If you need to use spaces or commas within the generated values (for example, if you need to use them within the values of the %SET macro), you can put the needed parameter in quotes. For example:

    %SET( Item1 ," Item2, Item3 ")

    This macro generates a set of the following values: 'Item1' and ' Item2, Item3 '.

    To include the quote ( ") symbol into the list of generated values when it is specified within the macro parameters, duplicate it, that is, use "". For example:

    %SET(!, $, "")

    This macro generates a set of the following values: ! (exclamation point), $ (dollar sign) and " (quote).

  • Both macro names and parameter values are case-insensitive.

  • The parameters that are not specified have their default values.

  • Unknown parameters and unsupported parameter values are ignored. For example, the available values for the Boolean generator are True/False, Yes/No and 1/0. Any unsupported value, like Allow/Deny, is ignored and the default True/False value is used instead.

  • The parameter values correspond to the values that you see in the Generate Value dialog for the generator. For instance, the Computer Address generator has an Address type parameter that can accept either IPv4, or MAC48 values. You can use these values for the %COMP macro in the custom string generator settings.

  • Some parameters have specific identifications. See Specific Identification for Some Parameters.

  • You can use neither regular expressions, nor macros as macro parameters. For example, the following syntax is invalid:

    %SET(%COUNTRY, %CITY, *SEQ) <-- Incorrect! Uses %COUNTRY and %CITY macros as parameters
    %SET({[a-z]},5, [1-9]+, *SEQ) <-- Incorrect! Uses regular expressions as parameters

  • You can use special format specifiers to customize the format of the generated string. For instance, you can use the following macro to generate a sequence of integer values with the specified minimum length (3 characters). If the length of the generated value is less than the specified constant, TestComplete adds the needed number of leading zeros to the value.

    %0.3d%INT(1, 100, 3)

    For information on available specifiers, see Format Specifiers.

Regular Expression Tokens

  • For complete information on the regular expressions that the Custom String generator uses, see Custom-String Generator - Supported Regular Expressions. Note that these regular expressions differ from the regular expressions supported by the Find dialog of TestComplete.

  • The regular expressions are used only if the Use regular expressions parameter of the Custom String generator is enabled. If this parameter is disabled, TestComplete treats regular expression parts as string literals. If the check box is selected, all the string literals are treated as regular expressions.

  • If you use regular expressions, you should escape special characters like brackets, parentheses, periods and others with backslashes in the Value string of the Custom String generator. See below.

  • Macros cannot be parameters of regular expressions.

Characters That Need Special Handling

  • To include the percent ( %) symbol into the generated string, duplicate it, that is, use %%.

  • If you use regular expressions and you need some special characters to be treated literally, precede them with backslashes. The special characters include brackets, parentheses, periods and others:

    For these symbols Use these strings
    \ \\
    [ and ] \[ and \]
    ( and ) \( and \)
    . \.
    + \+

    Special characters are tokens of regular expressions that are understood by the Custom String generator. For a complete list of tokens, see Custom-String Generator - Supported Regular Expressions.

See Also

About Custom String Generator
Generators
Using Data Generators
Generate Data Dialog

Highlight search results