This topic explains how to configure monitoring for databases.
Sections include:
Difference Between Event Monitor and DB Tools
The Event Monitor allows you to execute a SQL query on a database of your choice after each test executes within the test suite.
Although the DB Tool can be used for similar purposes, the Event Monitor Database mode is better suited for retrieving database rows when events occur as a result of your application logging messages into a database.
The Event Monitor is different than the DB Tool in a number of ways:
- A single Event Monitor in your test suite can execute database queries automatically after each test execution. This relieves you from having to add a DB Tool directly after each test.
- It allows delayed query execution (see the "Event polling delay after each test finishes execution" option under the Options tab). This is important for many logging databases because the logged entries may not reach the database in real time.
- It can consolidate the database entries into a single flow of events within a test suite, while the DB Tool gives you the flexibility to execute isolated and different queries at the desired points of your use case scenario.
- It helps you isolate the entries that were added to the database during test execution.
Configuration
Double-click the Event Monitor tool to open up the tool configuration panel.
Configuring the Event Source
Click the Event Source tab and configure the following settings:
| Platform | Choose Database from the platform dropdown menu. |
|---|---|
| Database Connection Settings | With Local selected, enter the Driver, URL, Username, and Password for the database you want to query. For details on completing these fields, see Database Configuration Parameters. |
| Constraint SQL Query (Optional) | Enter a value that identifies the last logged value from the database before a test executes. Event Monitor expects that query to return a single value. Typically, this would be a table key, an entry number, or a Timestamp. Using a constraint query is useful when your logging database is cumulative, and it is not cleaned/restored after each scenario executes. By executing this query before the test suite tests execute, the Event Monitor can distinguish the pre-existing entries from the new entries that will be logged into the database during test execution. Such queries would typically use the SQL MAX function. For example, the query select max(MESSAGE_TIMESTAMP) from MESSAGE_LOG assumes that you have a table named MESSAGE_LOG that contains a column named MESSAGE_TIMESTAMP of type Timestamp. It will return a single value representing the latest message entry currently present in that database. Event Monitor will execute that query first and keep that timestamp value. |
| Event SQL Query | Specify the SQL for retrieving the log or event entry from the database. Example query: select * from MESSAGE_LOG where MESSAGE_TIMESTAMP > $[CONSTRAINT] order by MESSAGE_TIMESTAMP DESC Note that $[CONSTRAINT] is a special SOAtest variable. It tells the Event Monitor to use the value it received from the first constraint query (described in the previous step) and automatically provide it in the event query. The event query executes after test suite execution completes (and after the delay specified in the Event Monitor’s Options tab). It retrieves the rows that were added to the database after the test executed. Use of $[CONSTRAINT] in event queries is not required. |
Configuring Event Monitoring Options
Click the Options tab and modify settings as needed.
| Clear the event viewer before each event monitor run | Enable this option to automatically clear the Event Monitor event view (both text and graphical) whenever Event Monitor starts monitoring. |
|---|---|
| Include test execution events in the XML event output to chained tools | Enable this option to show only the monitored messages and events in the Event Viewer tab and XML output display. This option also indicates when each test started and completed. Enabling this option is helpful if you have multiple tests in the test suite and you want to better identify the events and correlate them to your test executions. |
| Wrap monitored messages with CDATA to ensure well-formedness of the XML event output | Enable this option if you do not expect the monitored events’ message content to be well-formed XML. Disabling this option will make the messages inside the events accessible via XPaths, allowing the message contents to be extracted by XML Transformer or validated with XML Assertor tools. Enable this option if the message contents are not XML. This ensures that the XML output of the Event Monitor tool (that is, the XML Event Output for chaining tools to the Event Monitor, not what is shown under the Event Viewer) is well-formed XML by escaping all the message contents. This will make the content of these messages inaccessible by XPath since the message technically becomes just string content for the parent element. The Diff tool’s XML mode supports string content that is XML. As a result, the Diff tool will still be able to diff the messages as XML, including the ability to use XPaths for ignoring values, even if this option is disabled. |
| Maximum time to wait for the monitor to start (milliseconds) | Specify the maximum length of time the Event Monitor should wait to finish connecting to the event source before SOAtest runs the other tests in the suite. This enables SOAtest to capture events for those tests and prevents SOAtest from excessively blocking the execution of the other tests if the Event Monitor is having trouble connecting to its event source. Increase the value if connecting to the event source takes more time than the default. The default is 3000. |
| Maximum monitor execution duration (milliseconds) | Specify the point at which the test should timeout if, for example, another test in the test suite hangs or if no other tests are being run (for example, if you execute the Event Monitor test apart from the test suite, then use a custom application to send messages to system). |
| Event polling delay after each test finishes execution (milliseconds) | Specify how long Event Monitor should wait between the time the test ends and the time it retrieves the events. |
Notes
- The Event Viewer tab will display each row retrieved by the Event SQL query as a box in the event sequence flow. Double-clicking the box opens a dialog with data details.
- You can chain XML tools to a database Event Monitor. Since the database rows are output in XML, they can be diffed, validated with XML Assertor, and so on.
