Database Modules

The folder TBox XEngines->Database in the Standard subset contains Modules that perform specific tasks for the Database Engine 3.0.

The Database Engine 3.0 does not support mixed TestCases.

If you use the Database Engine 3.0 Module to open a connection, you must perform your database operations and then close the connection with Database Engine 3.0 Modules.

TBox DB Open Connection

The Module TBox DB Open Connection allows you to open a connection to a database.

You can open multiple database connections. The Database Engine 3.0 uses the most recently established connection for your tests.

Alternatively, you can specify a different connection with the Module Current Connection.

The Module TBox DB Open Connection has the following ModuleAttributes:

ModuleAttribute

Description

Connection name

Name of the connection that you want to open.

This is optional. By default, the Database Engine 3.0 uses the DSN value as connection name.

If you enter a Connection name that already exists, the Database Engine 3.0 doesn't establish a new connection.

DSN

Data source name for ODBC databases.

If you want to connect to SQLite, MS SQL, or generic ODBC databases, use Connection string.

DSN->User ID

ID of the user that opens the connection.

DSN->Password

Password of the user.

Connection string

Connection string to connect to SQLite, MS SQL, or generic ODBC databases.

For SQLite, the required drivers are part of the Tricentis Tosca standard installation.

Connection string->Driver

Specify whether you are using an SQLite, MSSQL, or generic ODBC database. To do so, select the respective value from the Value drop-down menu.

This example shows how to establish a connection to the database DB_Test.

The Database Engine 3.0 performs the following actions:

  • It saves the connection as a resource with the name TestDatabase.

  • It opens the connection with the user credentials of the user sa.

Open a database connection

In this example, you connect to the SQLite database mydb.db with the connection string Data Source=c:\mydb.db;Version=3;Password=myPassword;.

The Database Engine 3.0 saves the connection as a resource with the name SampleDatabase.

Connect to SQLite database

TBox DB Current Connection

This Module allows you to specify that you want to use a different connection than the most recently opened connection.

It has the following ModuleAttribute:

ModuleAttribute

Description

Connection name

Connection name of the connection that you want to use.

In this example, you define the connection with the name SampleDatabase as your Current Connection.

Establish a different current connection

TBox DB Close Connection

By default, the Database Engine 3.0 closes all open connections once it has finished the execution.

Alternatively, you can manually close the connection with the Module TBox DB Close Connection. In this case, the Database Engine 3.0 also deletes the resource that you created when you opened a connection.

Tricentis recommends that you pay close attention to which connection you close. Only close connections that you don't need in a subsequent TestCase.

The Module TBox DB Close Connection has the following ModuleAttribute:

ModuleAttribute

Description

Connection name

Connection name of the connection that you want to close.

This example closes the connection with the nameTestDatabase.

Close a database connection

TBox DB Run SQL Statement

This Module allows you to steer data sets of one or more database tables.

It accesses the database of the most recently opened connection. If you specified a different connection with the Module TBox DB Current Connection, then the Module accesses this database instead.

The Module TBox DB Run SQL Statement has the following ModuleAttributes:

ModuleAttribute

Description

SQL Statement

SQL statement that you want to run.

Command Timeout

Time in seconds that the Database Engine 3.0 should wait before it aborts the SQL statement and reports it as failed.

The default timeout is 60 seconds.

If you set the value to 0, the Database Engine 3.0 waits indefinitely.

Result Table

If needed, you can buffer or verify the table property RowsAffected. This property indicates how many rows the specified SQL statement affected.

If the statement didn't affect any rows, the value is 0. For SELECT statements, the value is -1.

You can export the result of your SQL Statement into a comma separated file. For more information, see chapter "Export the result of an SQL Statement".

Row / Row->Cell

Specify the cell in a particular row that you want to steer.

For information on how to steer tables, see chapter "Table".

The Database Engine 3.0 supports all read-only table steering ActionModes. It does not support ActionModes Input and Insert.

Column / Column->Cell

Specify the cell in a particular column that you want to steer.

For information on how to steer tables, see chapter "Table".

The Database Engine 3.0 supports all read-only table steering ActionModes. It does not support ActionModes Input and Insert.

In this example, the Database Engine 3.0 verifies whether the value of the first data row in the column Last name is Sorensen.

In this case, table steering interprets the table header as row #1. Therefore, the first data row of the table is row #2.

Verify the content of a table cell

In this example, you steer the table mytable:

  • Set all salaries that are lower than 30000 to the value 30000.

  • Verify that this SQL Statement affected 47 rows.

Verify the number of affected rows

TBox DB Expert module

The Module TBox DB Expert module allows you to handle your database statements with a single Module.

If you use Tosca DI, Tricentis recommends that you use the DI DB Expert Module from the Tosca Data Integrity Modules And Samples.tsu subset. This Module has the same base functionality, but allows you to use the connections you have defined in the Tosca DI Connection Manager.

If you run a 64-bit operating system, you can use both 32-bit and 64-bit ODBC connections.

If you run a 32-bit operating system, you can only use 32-bit ODBC connections.

The Module TBox DB Expert module has the following ModuleAttributes:

ModuleAttribute

Description

Open Connection

Read-only.

Open Connection->Connection name

Name of the connection that you want to use, if you have already opened a connection.

You can also open a new connection. In this case, use Connection Name together with one of the following connection identifiers:

  • DSN, User ID, and Password

  • Connection String

Open Connection->DSN

Data source name for ODBC databases.

If you want to connect to SQLite, MS SQL, or generic ODBC databases, use Connection string.

Open Connection->DSN->User ID

ID of the user that opens the connection.

Open Connection->DSN->Password

Password of the user.

Open Connection->Connection String

Connection string to connect to SQLite, MS SQL, or generic ODBC databases.

For SQLite, the required drivers are part of the Tricentis Tosca standard installation.

Open Connection->Connection String->Driver

Specify whether you are using an SQLite, MSSQL, or generic ODBC database. To do so, select the respective value from the Value drop-down menu.

SQL Statement

SQL statement that you want to run.

Command Timeout

Time in seconds that the Database Engine 3.0 should wait before it aborts the SQL statement and reports it as failed.

The default timeout is 60 seconds.

If you set the value 0, the Database Engine 3.0 waits indefinitely.

Result Table

If needed, you can buffer or verify the table property RowsAffected. This property indicates how many rows the specified SQL statement affected (see this example).

If the statement didn't affect any rows, the value is 0. For SELECT statements, the value is -1.

You can export the result of your SQL Statement into a comma separated file. For more information, see chapter "Export the result of an SQL Statement".

Row / Row->Cell

Specify the cell in a particular row that you want to steer.

For information on how to steer tables, see chapter "Table".

The Database Engine 3.0 supports all read-only table steering ActionModes. It does not support ActionModes Input and Insert.

Column / Column->Cell

Specify the cell in a particular column that you want to steer.

For information on how to steer tables, see chapter "Table".

The Database Engine 3.0 supports all read-only table steering ActionModes. It does not support ActionModes Input and Insert.

Close connection

Specify whether you want to close the connection:

  • Value True closes the connection. This is the default value.

  • Value False keeps the connection open.

In this example, you use the TBox DB Expert module to perform the following actions:

  • Establish a connection to the database DB_Test with the user credentials of the user sa.

  • Save the connection under the name TestDatabase.

  • Check the database table Customers.

  • Save the street number in the first data row of the column Street Number to a Buffer named StreetNumberBuffer.

  • Close the connection.

Use the TBox DB Expert module in a TestCase