global yes This library supports database-related testing using the Robot Framework. Itallows to establish a connection to a certain database to perform tests onthe content of certain tables and/or views in that database. A possiblescenario for its usage is a Web-Application that is storing data to thedatabase based on some user actions (probably a quite common scenario). Theactions in the Web-Application could be triggered using some tests based onSelenium and in the same test it will then be possible to check if the properdata has ended up in the database as expected. Of course there are variousother scenarios where this library might be used. As this library is written in Java support for a lot of different databasesystems is possible. This only requires the corresponding driver-classes(usually in the form of a JAR from the database provider) and the knowledgeof a proper JDBC connection-string. The following table lists some examples of drivers and connection stringsfor some popular databases. | *Database* | *Driver Name* | *Sample Connection String* | *Download Driver* | *Maven dependencies* | | MySql | com.mysql.jdbc.Driver | jdbc:mysql://servername/dbname | http://dev.mysql.com/downloads/connector/j/ | http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22mysql%22%20AND%20a%3A%22mysql-connector-java%22 | | Oracle | oracle.jdbc.driver.OracleDriver | jdbc:oracle:thin:@servername:port:dbname | http://www.oracle.com/technology/tech/java/sqlj_jdbc/htdocs/jdbc_faq.html | https://blogs.oracle.com/dev2dev/entry/oracle_maven_repository_instructions_for | The examples in the description of the keywords is based on a database tablenamed "MySampleTable" that has the following layout: MySampleTable: | *COLUMN* | *TYPE* | | Id | Number | | Name | String | | EMail | String | | Postings | Number | | State | Number | | LastPosting | Timestamp | *NOTE*: A lot of keywords that are targeted for Tables will work equally with Views as this is often no difference if Select-statements are performed. *Remote Library Support* At release 3.0 remote functionalities were removed from the library itself. Library can be used directly with jrobotremoteserver (https://github.com/ombre42/jrobotremoteserver/wiki/Getting-Started). Example can be found at project's acceptance tests: https://github.com/Hi-Fi/robotframework-dblibrary/tree/master/src/test/robotframework/acceptance Database alias=default Activates the database connection with given alias. Please note that connection has to be opened earlier. Example: | Activate Database Connection | ownAlias | Column names (comma separated) Expected values (pipe separated) Table name Number of row to check This keyword can be used to check for proper content inside a specific row in a database table. For this it is possible to give a comma-separated list of column names in the first parameter and a pipe-separated list of values in the second parameter. Then the name of the table and the rownum to check must be passed to this keyword. The corresponding values are then read from that row in the given table and compared to the expected values. If all values match the teststep will pass, otherwise it will fail. Example: | Check Content for Row Identified by Rownum | Name,EMail | John Doe|john.doe@x-files | MySampleTable | 4 | Column names (comma separated) Expected values (pipe separated) Table name Where clause to identify the row This keyword can be used to check for proper content inside a specific row in a database table. For this it is possible to give a comma-separated list of column names in the first parameter and a pipe-separated list of values in the second parameter. Then the name of the table and a statement used in the where-clause to identify a concrete row. The corresponding values are then read from the row identified this way and compared to the expected values. If all values match the teststep will pass, otherwise it will fail. If the where-clause will select more or less than exactly one row the test will fail. Example: | Check Content for Row Identified by WhereClause | Name,EMail | John Doe|john.doe@x-files | MySampleTable | Postings=14 | Table name Comma separated list of primary key columns to check Checks that the primary key columns of a given table match the columns given as a comma-separated list. Note that the given list must be ordered by the name of the columns. Upper and lower case for the columns as such is ignored by comparing the values after converting both to lower case. *NOTE*: Some database expect the table names to be written all in upper case letters to be found. Example: | Check Primary Key Columns For Table | MySampleTable | Id,Name | Query to execute File to compare results with Executes the given SQL compares the result to expected results stored in a file. Results are stored as strings separated with pipes ('|') with a pipe following the last column. Rows are separated with a newline. To ensure compares work correctly The SQL query should a) specify an order b) convert non-string fields (especially dates) to a specific format storeQueryResultToFile can be used to generate expected result files *NOTE*: If using keyword remotely, file need to be trasfered to server some other way; this library is not doing the transfer. Example: | Compare Query Result To File | Select phone, email from addresses where last_name = 'Johnson' | query_result.txt | Driver class name Connection string Database username Database password Database alias=default Establish the connection to the database. This is mandatory before any ofthe other keywords can be used and should be ideally done during the suite setup phase. To avoid problems ensure to close the connection again using the disconnect-keyword. It must be ensured that the JAR-file containing the given driver can be found from the CLASSPATH when starting robot. Furthermore it must be noted that the connection string is database-specific and must be valid of course. If alias is given, connection can be later referred with that. If alias was in use, existing connection is replaced with new one Example: | Connect To Database | com.mysql.jdbc.Driver | jdbc:mysql://my.host.name/myinstance | UserName | ThePassword | default | Table name Deletes the entire content of the given database table. This keyword isuseful to start tests in a clean state. Use this keyword with care asaccidently execution of this keyword in a productive system will causeheavy loss of data. There will be no rollback possible. Example: | Delete All Rows From Table | MySampleTable | Database alias=default Releases the existing connection to the database. In addition thiskeyword will log any SQLWarnings that might have been occurred on the connection. If current connection is closed and there's still some open, you have to activate that manually. Example: | Disconnect from Database | default | SQL String to execute Executes the given SQL without any further modifications. The given SQL must be valid for the database that is used. Results are returned as a list of dictionaries *NOTE*: Use this method with care as you might cause damage to your database, especially when using this in a productive environment. Example: | Execute SQL | CREATE TABLE MyTable (Num INTEGER) | File containing SQL commands to execute Executes the SQL statements contained in the given file without any further modifications. The given SQL must be valid for the database that is used. Any lines prefixed with "REM" or "#" are ignored. This keyword can for example be used to setup database tables from some SQL install script. Single SQL statements in the file can be spread over multiple lines, but must be terminated with a semicolon ";". A new statement must always start in a new line and not in the same line where the previous statement was terminated by a ";". In case there is a problem in executing any of the SQL statements from the file the execution is terminated and the operation is rolled back. *NOTE*: Use this method with care as you might cause damage to your database, especially when using this in a productive environment. *NOTE2*: If using keyword remotely, file need to be trasfered to server some other way; this library is not doing the transfer. Example: | Execute SQL from File | myFile.sql | File containing SQL commands to execute Executes the SQL statements contained in the given file without any further modifications. The given SQL must be valid for the database that is used. Any lines prefixed with "REM" or "#" are ignored. This keyword can for example be used to setup database tables from some SQL install script. Single SQL statements in the file can be spread over multiple lines, but must be terminated with a semicolon ";". A new statement must always start in a new line and not in the same line where the previous statement was terminated by a ";". Any errors that might happen during execution of SQL statements are logged to the Robot Log-file, but otherwise ignored. *NOTE*: Use this method with care as you might cause damage to your database, especially when using this in a productive environment. *NOTE2*: If using keyword remotely, file need to be trasfered to server some other way; this library is not doing the transfer. Example: | Execute SQL from File | myFile.sql | Table name Export file path (including name) Where clause= Exports the data from the given table into a file that is stored at the given location. The where-clause can (and should) be used to narrow the amount of rows that is exported this way. The file is stored in some simple XML-format and can be imported again to the database using the "Import Data From File" keyword. This way it is possible to store a set of testdata permanently retrieving it for example from some Live- or Demosystem. This keyword will probably have some issues if millions of rows are exported/imported using it. *NOTE*: If using keyword remotely, file need to be trasfered to server some other way; this library is not doing the transfer. The keyword returns the amount of rows written to the XML-file. Example: | ${ROWSEXPORTED}= | MySampleTable | /tmp/mysampletable.xml | Timestamp > sysdate-50 | Table name Returns a comma-separated list of the primary keys defined for the given table. The list if ordered by the name of the columns. *NOTE*: Some database expect the table names to be written all in upper case letters to be found. Example: | ${KEYS}= | Get Primary Key Columns For Table | MySampleTable | Returns a String value that contains the name of the transaction isolation level of the connection that is used for executing the tests. Possible return values are: TRANSACTION_READ_UNCOMMITTED, TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE or TRANSACTION_NONE. Example: | ${TI_LEVEL}= | Get Transaction Isolation Level | File containing XML data to be imported This keyword reads data from a XML-file and stores the corresponding data to the database. The file must have been created using the "Export Data From Table" keyword or it must be created manually in the exact format. The XML-file contains not only the data as such, but also the name of the schema and table from which the data was exported. The same information is used for the import. *NOTE*: If using keyword remotely, file need to be trasfered from server some other way; this library is not doing the transfer. The keyword returns the amount of rows that have been successfully stored to the database table. Example: | ${ROWSIMPORTED}= | /tmp/mysampletable.xml | Table name Column to get Where clause to identify the row Reads a single value from the given table and column based on the where-clause passed to the test. If the where-clause identifies more or less than exactly one row in that table this will result in an error for this teststep. Otherwise the selected value will be returned. Example: | ${VALUE}= | Read single Value from Table | MySampleTable | EMail | Name='John Doe' | Table to check Where clause This keyword can be used to check the inexistence of content inside a specific row in a database table defined by a where-clause. This can be used to validate an exclusion of specific data from a table. Example: | Row Should Not Exist In Table | MySampleTable | Name='John Doe' | This keyword was introduced in version 1.1. Query to execute File to save results Executes the given SQL without any further modifications and stores the result in a file. The SQL query must be valid for the database that is used. The main purpose of this keyword is to generate expected result sets for use with keyword compareQueryResultToFile *NOTE*: If using keyword remotely, file need to be trasfered from server some other way; this library is not doing the transfer. Example: | Store Query Result To File | Select phone, email from addresses where last_name = 'Johnson' | query_result.txt | Table name Checks that the given table has no rows. It is a convenience way of using the 'Table Must Contain Number Of Rows' with zero for the amount of rows. Example: | Table Must Be Empty | MySampleTable | Table name Number of rows too high This keyword checks that a given table contains less than the given amount of rows. For the example this means that the table "MySampleTable" must contain anything between 0 and 1000 rows, otherwise the teststep will fail. Example: | Table Must Contain Less Than Number Of Rows | MySampleTable | 1001 | Table name Number of rows too low This keyword checks that a given table contains more than the given amount of rows. For the example this means that the table "MySampleTable"must contain 100 or more rows, otherwise the teststep will fail. Example: | Table Must Contain More Than Number Of Rows | MySampleTable | 99 | Table name Amount of rows expected This keyword checks that a given table contains a given amount of rows. For the example this means that the table "MySampleTable" must contain exactly 14 rows, otherwise the teststep will fail. Example: | Table Must Contain Number Of Rows | MySampleTable | 14 | Table name Checks that a table with the given name exists. If the table does not exist the test will fail. *NOTE*: Some database expect the table names to be written all in upper case letters to be found. Example: | Table Must Exist | MySampleTable | First table name Second table name This keyword checks that two given database tables have the same amount of rows. Example: | Tables Must Contain Same Amount Of Rows | MySampleTable | MyCompareTable | Isolation level Can be used to check that the database connection used for executing tests has the proper transaction isolation level. The string parameter accepts the following values in a case-insensitive manner: TRANSACTION_READ_UNCOMMITTED, TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE or TRANSACTION_NONE. Example: | Transaction Isolation Level Must Be | TRANSACTION_READ_COMMITTED | Table to check Where clause Expected number of rows This keyword checks that a given table contains a given amount of rows matching a given WHERE clause. For the example this means that the table "MySampleTable" must contain exactly 2 rows matching the given WHERE, otherwise the teststep will fail. Example: | Verify Number Of Rows Matching Where | MySampleTable | email=x@y.net | 2 |