Dev release 4.4.0

• Support for disabling of order verification for simple collection
• Switch for events publication in checkpoint request. Parameter enable-checkpoint-events-publication should be used for that
• WaitForResult method added

Dev-Release 4.3.0-dev

Added:

• Configure number of threads for rules execution. Parameter rules-execution-threads

Updated:

• common: 5.6.0-dev
• grpc-check1: 4.3.0-dev
• rxjava: 2.2.21

Merged

• Changes from 3.10.0 version
  • Added:
    • Support for disabling of order verification for simple collection
    • Switch for events publication in checkpoint request. Parameter enable-checkpoint-events-publication should be used for that.
  • Changed:
    • Migrated sailfish-utils version from 3.12.2 to 3.12.3
    • Improved condition output format for EQ_PRECISION, WILDCARD, LIKE, IN, MORE, LESS operations and their
      negative versions
    • Changed the way the check1 works with threads internally.
      Now it uses a common executor for running check rules instead of creating an executor per each rule

Release 3.9.0

What's new in release 3.9.0

To work with check1 3.9.0 you need to install the grpc-check1 library with version 3.5.1 or higher.

New features

Silence check after CheckSequence rule and NoMessageCheck rule

There are some cases when you expect some messages sequence to be received and nothing more matches key fields in that sequence is received after that.
In the previous check1 version, there was no such functionality.
The release 3.9.0 introduces two ways of doing that:

• Automated silence check after CheckSequence rule;
• NoMessageCheck rule for manual verification.

Silence check

This functionality adds verification that no more messages that match the pre-filter in the CheckSequence rule
was received after the rule main CheckSequence rule is completed.
The timeout for which the silence check awaits the messages is either the cleanup timeout (cleanup-older-than + cleanup-time-unit) is exceeded
or the next rule has been submitted to the chain.
You can enable it per request by silence_check parameter.

from google.protobuf import wrappers_pb2 as wrappers

CheckSequenceRuleRequest(
  # ...
  silence_check=wrappers.BoolValue(value=True) # or False, or you might not set silence_check at all
)

import com.exactpro.th2.check1.grpc.CheckSequenceRuleRequest;

CheckSequenceRuleRequest.newBuilder()
    .setSilenceCheck(BoolValue.of(true)) // or false, or you might not set silenceCheck at all

If it is not set the silence check will be added automatically if the auto-silence-check-after-sequence-rule in check1 configuration is enabled.

NoMessagesCheck rule

This rule allows you to check that no messages that match the specified filter were received during a certain time period.
It is very similar to the silence check but can be used independently.
The timeout for the rule might be specified based on real-time or messages time.

Timeout for rules based on the message's time

The current version of check1 allows you to specify the timeout that is based on real-time.
When a user specifies the small timeout to make sure that messages were received quickly enough it might cause unexpected rule failure.
It happens because check1 processes messages with a different speed depending on the load and resources.
And in some cases, the message you need to verify might be received by check1 but not yet processed.

Here comes the message_timeout parameter. It allows you to specify the timeout based on the messages' timestamps.
Please note, that using message_timeout requires either a checkpoint or an existing chain_id.
They are required to compute borders for message timestamp.
You can specify a small message_timeout and a bigger timeout to allow check1 process messages.
When it sees the message with a timestamp that exceeds the computed borders it completes the rule.

Default timeout

There is a new rule-execution-timeout parameter that allows you to specify the default timeout
for rule execution if the request does not contain one.
It allows you to specify only the message_timeout in the request.

Precision for comparing numbers and date-time values

The new version of check1 allows you to use precision for comparing numbers and date-time values.
To get the advantage of comparison with the precision you should use EQ_TIME_PRECISION or EQ_DECIMAL_PRECISION operation
depending on the value type you try to compare.
There are default precisions for those operations. They can be specified using time-precision and decimal-precision parameters in check1 configuration.
Also, you can specify the precision per filter. The RootComparisonSettings now has two parameters:

• time_precision - is used to specify the precision for comparing date-time values (please note, that they should be represented in ISO format)
  Examples:

  import datetime
  
  td = datetime.timedelta(days=3, minutes=10)
  duration = Duration()
  duration.FromTimedelta(td)
  RootComparisonSettings(
    # other parameters
    time_precision=duration
  )

  import com.exactpro.th2.common.grpc.RootComparisonSettings;
  import com.google.protobuf.util.Durations;
  
  RootComparisonSettings.newBuilder()
    .setTimePrecision(Durations.fromMillis(100))
    .build();

• decimal_precision - is used to specify the precision for comparing numbers. Can be in engineering format and the regular one (e.g. 125E-3 or 0.125)

Null value filter

Now you can assert that the message contains some field with null value (the field presents in the message but it has a value of null).
NOTE: only EQUAL and NOT_EQUAL operations are supported.

Example:

ValueFilter(
  operation=FilterOperation.EQUAL,
  null_value=NullValue
)

import com.exactpro.th2.common.grpc.ValueFilter;
import com.exactpro.th2.common.grpc.NullValue;

ValueFilter.newBuilder()
    .setOperation(FilterOperation.EQUAL)
    .setNullValue(NullValue.NULL_VALUE)
    .build();

Changes

Consider null value in a message as empty

The default behavior regarding null values in a message has been changed in check1.
If the field presents in the message and has the value null the EMPTY filter won't pass anymore.
The opposite for NOT_EMPTY. It will pass in case the field exists but has a null value.
If you want to enable the old behavior you can switch it using check-null-value-as-empty parameter in the check1 configuration.

Failure reason improvements

When you specify the filter and the actual message has that field but the content type is different (you expected the simple value but a sub-message was received in the message)
the old version of check1 did not say anything useful and just marked the field as failed.
Also, when something happened during field comparison there was no information about what has happened.
Starting with version 3.9.0 the hint is added in these cases. You will see in the UI a message that explains what has happened.
NOTE: this improvement will work only with a report-viewer version 3.1.95 or higher.

Displaying null and string values in verification

The previous version of check1 did not separate the null value and the string "null".
It might cause a misunderstanding of the verification result. Version 3.9.0 reports the values regarding the actual value.

NOTE: this improvement will work only with a report-viewer version 3.1.102 or higher.

Fixes

failUnexpected parameter was not propagated to sub-messages

There was a problem when you specify the failUnxpected parameter but fields in sub-messages (or collections of messages)
does not cause a failure. That was happening because the parameter's value was not propagated to the sub-messages.

Incorrect matching of repeating groups

There was a problem with matching repeating groups when the filter contains fewer elements than the actual message
and they are received in a different order. In this case, check1 might match the incorrect elements and the verification result might confuse users.

Release 3.8.0

What’s new in release 3.8.0

To work with check1 3.8.0 you need to install the grpc-check1 library with version 3.4.2 or higher.

New features

Description for each verification in CheckSequenceRule

Now RootMessageFilter has an optional field description that can be used to add custom information to a verification event in check1.

from google.protobuf import wrappers_pb2 as wrappers

# ...

RootMessageFilter(
  messageType="YourMessage",
  message_filter=MessageFilter(...),
  description=wrappers.StringValue("You description")
)

New filter operations are added to ValueFilter

Check1 now has support for new operation for checking field's value:

IN/NOT_IN - check if the value of the field presents/does not present in the specified list

ValueFilter(
    simple_list=SimpleList(simple_values=["A", "B"]),
    operation=FilterOperation.IN # or FilterOperation.NOT_IN
)

LIKE/NOT_LIKE - check if the value of the field matches or not the specified regexp

ValueFilter(
    simple_filter="your[Rr]egexp.*",
    operation=FilterOperation.LIKE # or FilterOperation.NOT_LIKE
)

LESS/MORE/NOT_LESS/NOT_MORE - compares the value of the field with the specified value. Works for decimal values and DateTime values (in ISO-8601 format)

ValueFilter(
    simple_filter="42",
    operation=FilterOperation.LESS
)

For DataTime

ValueFilter(
    simple_filter="2007-12-03T10:15:30",
    operation=FilterOperation.NOT_LESS
)

WILDCARD/NOT_WILDCARD - similar to the LIKE/NOT_LIKE but uses wildcard matching instead of regexp.

ValueFilter(
    simple_filter="your?egexp*", # ? - any symbol, * - zero or more symbols
    operation=FilterOperation.WILDCARD # or FilterOperation.NOT_WILDCARD
)

Checking metadata properties.

A new MetadataFilter was added to RootMessageFilter and PreFilter. Can be used to check metadata properties. Supports all new operations.

Examples:

from th2_grpc_check1.check1_pb2 import PreFilter
from th2_grpc_common.common_pb2 import RootMessageFilter, MetadataFilter, FilterOperation

# ...

# message filter
RootMessageFilter(
    metadata_filter=MetadataFilter(
        property_filters={
            'test.prop': MetadataFilter.SimpleFilter(
                operation=FilterOperation.EQUAL,
                value="test"
            ),
            'another.prop': MetadataFilter.SimpleFilter(
                operation=FilterOperation.IN,
                simple_list=SimpleList(simple_values=["A", "B"])
            )
        }
    )
)

# pre-filter
PreFilter(
    metadata_filter=MetadataFilter(
        property_filters={
            'test.prop': MetadataFilter.SimpleFilter(
                operation=FilterOperation.EQUAL,
                value="test"
            ),
            'another.prop': MetadataFilter.SimpleFilter(
                operation=FilterOperation.IN,
                simple_list=SimpleList(simple_values=["A", "B"])
            )
        }
    )
)

Verify repeating groups order in the message.

Allows check1 to verify the order of the elements in the collection fields.
If the flag is set the check1 one will pass the comparison only if the actual order of elements in the collection matches the filter.

from th2_grpc_common.common_pb2 import RootMessageFilter, RootComparisonSettings, MessageFilter, ValueFilter, ListValue

# ...

RootMessageFilter(
    metadata_filter=MessageFilter(
        fields={
            'collection': ValueFilter(
                list_filter=ListValue(
                    values=[
                        ValueFilter(simple_filter="1"),
                        ValueFilter(simple_filter="2")
                    ]
                )
            )
        }
    ),
    comparison_settings=RootComparisonSettings(
        check_repeating_group_order=True
    )
)

Deprecations:

Some existing properties in message filters and rule requests were deprecated and will be removed in a future major release.
Please, check the list below and migrate from the deprecated properties to new ones.

RootMessageFilter instead of MessageFilter

CheckRuleRequest and CheckSequenceRuleRequest now uses RootMessageFilter for declaring the message's filter.
It contains the information about message type and filters for the message's body (message_filter field) and metadata (metadata_filter field).
The general settings for comparison were moved to the RootMessageFilter as well (RootComparisonSettings in comparison_settings field).

Old check rule request example:

CheckRuleRequest(
  connectivity_id=ConnectionID(session_alias='test'),
  filter=MessageFilter(
    messageType="A",
    comparison_settings=ComparisonSettings(
      ignore_fields=['a','b'],
      fail_unexpected=FailUnexpected.FIELDS
    ),
    fields={...}
  ),
  ...
)

New request:

CheckRuleRequest(
  connectivity_id=ConnectionID(session_alias='test'),
  root_filter=RootMessageFilter(
    messageType="A",
    message_filter=MessageFilter(
      fields={...},
      comparison_settings=ComparisonSettings(fail_unexpected=FailUnexpected.FIELDS)
    ),
    comparison_settings=RootComparisonSettings(
      ignore_fields=['a','b'],
      check_repeating_group_order=true
    )
  ),
  ...
)

Reporting improvements:

Add metrics for view number of active caches and actual cache size into check1

Check1 now exports a number of metrics that will help to get information about current check1's state.

• th2_check1_actual_cache_number - actual number of messages in caches
• th2_check1_active_tasks_number - actual number of currently working rules

The th2_check1_actual_cache_number metric uses two labels:

• session_alias - session alias of received message
• direction - direction of received message

The th2_check1_active_tasks_number metric use rule_type label

"No message found" table improvements

The event with submitted filters when no messages were found became more informative:

• Information about expected message's type and message's metadata extracted into a separate table;
• The expected values in the submitted filter are displayed in a more convenient way (the operation and values are joined together);
• Comparison settings extracted into a separate table.

Keep verification order for repeating groups matches the original order

The previous version of check1 displayed the elements of collections in verification from the best match to the worst match.
It could confuse users. They might start to think that the actual message has incorrect order of elements in the collection.
The new version respects the actual order and displays elements in the verification respectively.

Correct reporting about incorrect parameters and internal errors

The previous version of check1 did not notify a user about incorrect parameters or internal errors during the message processing.
Not check1 will verify request parameters and report an error if some parameters are not set or have incorrect values.
When an internal error has occurred the event with its description will be created and added to the report.

Correct root event name for rules

The previous version of check1 created root events with rule type prefix and session alias and direction pair before the description set by the user. The new version changes that. The root event name now consists of the rule type prefix and the user's description. The information about the session alias and direction was moved to the event body.

Fixes:

Submitted rule begins executing before it has been configured fully

There was an issue when the rule finds all it needs before it was fully initialized.
The new version fixes that issue and initializes the rule before it starts processing messages.

v2.4.0-beta

Version for demo-configuration and demo-script.