diff --git a/README.md b/README.md index b00f3f8d..ebdbf87b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![alt tag](img/assertj-db_icon.png) +![alt tag](src/main/docs/modules/ROOT/images/assertj-db_icon.png) AssertJ-DB - Assertions for database ========== diff --git a/src/main/docs/antora.yml b/src/main/docs/antora.yml new file mode 100644 index 00000000..9ffa6d85 --- /dev/null +++ b/src/main/docs/antora.yml @@ -0,0 +1,12 @@ +name: assertj-db +title: AssertJ DB +nav: +- modules/ROOT/nav.adoc +ext: + collector: + scan: + dir: src/test/java/org/example/db + into: modules/ROOT/examples +asciidoc: + attributes: + project-description: 'Provide assertions for Guava types (Multimap, Optional, ...)' diff --git a/img/assertj-db_icon.png b/src/main/docs/modules/ROOT/images/assertj-db_icon.png similarity index 100% rename from img/assertj-db_icon.png rename to src/main/docs/modules/ROOT/images/assertj-db_icon.png diff --git a/img/assertj-db_icon.xcf b/src/main/docs/modules/ROOT/images/assertj-db_icon.xcf similarity index 100% rename from img/assertj-db_icon.xcf rename to src/main/docs/modules/ROOT/images/assertj-db_icon.xcf diff --git a/img/assertj-db_icon_small.png b/src/main/docs/modules/ROOT/images/assertj-db_icon_small.png similarity index 100% rename from img/assertj-db_icon_small.png rename to src/main/docs/modules/ROOT/images/assertj-db_icon_small.png diff --git a/src/main/docs/modules/ROOT/images/db-changes-concept.png b/src/main/docs/modules/ROOT/images/db-changes-concept.png new file mode 100644 index 00000000..02cad892 Binary files /dev/null and b/src/main/docs/modules/ROOT/images/db-changes-concept.png differ diff --git a/doc/changes/assertions/diagramOfPartOnChangesWithAssertions.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/assertions/diagramOfPartOnChangesWithAssertions.dia similarity index 100% rename from doc/changes/assertions/diagramOfPartOnChangesWithAssertions.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/assertions/diagramOfPartOnChangesWithAssertions.dia diff --git a/doc/changes/diagramOfPartOnChanges.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/diagramOfPartOnChanges.dia similarity index 100% rename from doc/changes/diagramOfPartOnChanges.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/diagramOfPartOnChanges.dia diff --git a/doc/changes/navigation/diagramOfPartOnChangesWithNavigation.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOfPartOnChangesWithNavigation.dia similarity index 100% rename from doc/changes/navigation/diagramOfPartOnChangesWithNavigation.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOfPartOnChangesWithNavigation.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges_ToChange.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToChange.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges_ToChange.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToChange.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges_ToChanges.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToChanges.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges_ToChanges.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToChanges.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges_ToColumn.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToColumn.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges_ToColumn.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToColumn.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges_ToRow.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToRow.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges_ToRow.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToRow.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges_ToValue.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToValue.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges_ToValue.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToValue.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromColumn.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromColumn.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromColumn.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromColumn.dia diff --git a/doc/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromRow.dia b/src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromRow.dia similarity index 100% rename from doc/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromRow.dia rename to src/main/docs/modules/ROOT/images/diagrams/changes/navigation/diagramOnNavigationWithChanges_ToValue_FromRow.dia diff --git a/doc/output/diagramOfPartOnOutputOnChangesWithNavigation.dia b/src/main/docs/modules/ROOT/images/diagrams/output/diagramOfPartOnOutputOnChangesWithNavigation.dia similarity index 100% rename from doc/output/diagramOfPartOnOutputOnChangesWithNavigation.dia rename to src/main/docs/modules/ROOT/images/diagrams/output/diagramOfPartOnOutputOnChangesWithNavigation.dia diff --git a/doc/output/diagramOfPartOnOutputOnTableAndRequestWithNavigation.dia b/src/main/docs/modules/ROOT/images/diagrams/output/diagramOfPartOnOutputOnTableAndRequestWithNavigation.dia similarity index 100% rename from doc/output/diagramOfPartOnOutputOnTableAndRequestWithNavigation.dia rename to src/main/docs/modules/ROOT/images/diagrams/output/diagramOfPartOnOutputOnTableAndRequestWithNavigation.dia diff --git a/doc/table_and_request/assertions/diagramOfPartOnTableAndRequestWithAssertions.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/assertions/diagramOfPartOnTableAndRequestWithAssertions.dia similarity index 100% rename from doc/table_and_request/assertions/diagramOfPartOnTableAndRequestWithAssertions.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/assertions/diagramOfPartOnTableAndRequestWithAssertions.dia diff --git a/doc/table_and_request/diagramOfPartOnTableAndRequest.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/diagramOfPartOnTableAndRequest.dia similarity index 100% rename from doc/table_and_request/diagramOfPartOnTableAndRequest.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/diagramOfPartOnTableAndRequest.dia diff --git a/doc/table_and_request/navigation/diagramOfPartOnTableAndRequestWithNavigation.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOfPartOnTableAndRequestWithNavigation.dia similarity index 100% rename from doc/table_and_request/navigation/diagramOfPartOnTableAndRequestWithNavigation.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOfPartOnTableAndRequestWithNavigation.dia diff --git a/doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest.dia similarity index 100% rename from doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest.dia diff --git a/doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToColumn.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToColumn.dia similarity index 100% rename from doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToColumn.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToColumn.dia diff --git a/doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToRow.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToRow.dia similarity index 100% rename from doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToRow.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToRow.dia diff --git a/doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue.dia similarity index 100% rename from doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue.dia diff --git a/doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue_FromRow.dia b/src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue_FromRow.dia similarity index 100% rename from doc/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue_FromRow.dia rename to src/main/docs/modules/ROOT/images/diagrams/table_and_request/navigation/diagramOnNavigationWithTableOrRequest_ToValue_FromRow.dia diff --git a/doc/type/diagramOfTypeClasses.dia b/src/main/docs/modules/ROOT/images/diagrams/type/diagramOfTypeClasses.dia similarity index 100% rename from doc/type/diagramOfTypeClasses.dia rename to src/main/docs/modules/ROOT/images/diagrams/type/diagramOfTypeClasses.dia diff --git a/img/old_assertj-db_icon.png b/src/main/docs/modules/ROOT/images/old_assertj-db_icon.png similarity index 100% rename from img/old_assertj-db_icon.png rename to src/main/docs/modules/ROOT/images/old_assertj-db_icon.png diff --git a/img/old_assertj-db_icon.xcf b/src/main/docs/modules/ROOT/images/old_assertj-db_icon.xcf similarity index 100% rename from img/old_assertj-db_icon.xcf rename to src/main/docs/modules/ROOT/images/old_assertj-db_icon.xcf diff --git a/img/old_assertj-db_icon_small.png b/src/main/docs/modules/ROOT/images/old_assertj-db_icon_small.png similarity index 100% rename from img/old_assertj-db_icon_small.png rename to src/main/docs/modules/ROOT/images/old_assertj-db_icon_small.png diff --git a/src/main/docs/modules/ROOT/nav.adoc b/src/main/docs/modules/ROOT/nav.adoc new file mode 100644 index 00000000..13f5c1e8 --- /dev/null +++ b/src/main/docs/modules/ROOT/nav.adoc @@ -0,0 +1,14 @@ +* xref:index.adoc[] +* xref:quickstart.adoc[] +* xref:concepts/index.adoc[] +** xref:concepts/connection.adoc[Connection] +** xref:concepts/elements.adoc[Elements] +** xref:concepts/types.adoc[] +** xref:concepts/navigation.adoc[] +** xref:concepts/datetime.adoc[Date Time] +** xref:concepts/description.adoc[Description] +** xref:concepts/letter-case.adoc[Letter Case] +** xref:concepts/output.adoc[] +* xref:features/index.adoc[] +** xref:features/navigation.adoc[] +** xref:features/assertions.adoc[] diff --git a/src/main/docs/modules/ROOT/pages/concepts/connection.adoc b/src/main/docs/modules/ROOT/pages/concepts/connection.adoc new file mode 100644 index 00000000..2d952482 --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/connection.adoc @@ -0,0 +1,69 @@ += Connection to the database + +To make assertions on a database, it is necessary to connect. The concept of `AssertDbConnection` represent how +AssertJ-DB can retrieve data and schema information from database. + +It's also with a `AssertDbConnection` that you can instantiate the following element : `Table`, `Request`, `Changes`. + +[[AssertDbConnection]] +== AssertDbConnection + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnection.html[AssertDbConnection] +is created with the factory https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnectionFactory.html[AssertDbConnectionFactory]. + +There are 2 way to begin the AssertDbConnectionFactory, with a http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html[DataSource] ( the classic Java way +to get a http://docs.oracle.com/javase/6/docs/api/java/sql/Connection.html[Connection] to a database ) or with JDBC connection information. + +Below is an example of using a DataSource to connect to H2 in memory database : + +[source,java] +---- +AssertDbConnection connection = AssertDbConnectionFactory.of("jdbc:h2:mem:test", "sa", "").create(); +---- + +And using a DataSource to connect : + +[source,java] +---- +AssertDbConnection connection = AssertDbConnectionFactory.of(dataSource).create(); +---- + +== LetterCase setup + +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnectionFactory.html[AssertDbConnectionFactory] +provide the capacity to indicate the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] +to use for the tables, columns and primary keys. + +[source,java] +---- +AssertDbConnection connection = AssertDbConnectionFactory + .of(dataSource) + .letterCase(tableLetterCase, columnLetterCase, pkLetterCase) + .create(); +---- + +For more information, see the <>. + +== Schema retrieval mode + +For many assertions, AssertJ-DB require to discover database schema metadata ( list of tables, columns, ... ). +When the schema contains many tables this operation can slow down the tests executions. + +To avoid that and when the database schema is not updated during the test session, you can use the option +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/SchemaMetaDataMode.html[SchemaMetaDataMode] of +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnectionFactory.html[AssertDbConnectionFactory] +to keep in memory the schema. + +Available mode are : + + - DYNAMIC ( default ): Retrieve schema metadata each time is required. + - STATIC : Retrieve schema metadata only once and keep in memory for all duration of connection. + +Below is an example of using the STATIC mode for a connection : + +[source,java] +---- +AssertDbConnection connection = AssertDbConnectionFactory.of(dataSource) + .schemaMetaDataMode(SchemaMetaDataMode.STATIC) + .create(); +---- diff --git a/src/main/docs/modules/ROOT/pages/concepts/datetime.adoc b/src/main/docs/modules/ROOT/pages/concepts/datetime.adoc new file mode 100644 index 00000000..18fd5fea --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/datetime.adoc @@ -0,0 +1,84 @@ += DateValue, TimeValue and DateTimeValue + +The preferred way to compare values with date, time and date/time is to use java.time.LocalDate, java.time.LocalTime, java.time.LocalDateTime directly. + +But for the backward compatibility, it's always possible to use AssertJ-DB DateValue utilities. + +So The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/DateValue.html[DateValue], +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/TimeValue.html[TimeValue] and +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/DateTimeValue.html[DateTimeValue] classes are simpler but contains this kind of information. + +There is 4 kinds of static methods to instantiate these values : + +* `of` which receives the information as `int` parameters + +[source,java] +---- +DateValue dateValue = DateValue.of(2007, 12, 23); + +// With hours and minutes only +TimeValue timeValue1 = TimeValue.of(9, 1); +// With seconds additional +TimeValue timeValue2 = TimeValue.of(9, 1, 6); +// With nanoseconds additional +TimeValue timeValue3 = TimeValue.of(9, 1, 6, 3); + +// With date only (so hour is midnight) +DateTimeValue dateTimeValue1 = DateTimeValue.of(dateValue); +// With date and time +DateTimeValue dateTimeValue2 = DateTimeValue.of(dateValue, timeValue1); +---- + +* `from` which receives the equivalent from `java.sql` package (`java.sql.Date`, `java.sql.Time` and `java.sql.Timestamp`) +or a `java.util.Calendar` + +[source,java] +---- +Date date = Date.valueOf("2007-12-23"); +DateValue dateValue = DateValue.from(date); + +Time time = Time.valueOf("09:01:06"); +TimeValue timeValue = TimeValue.from(time); + +Timestamp timestamp = Timestamp.valueOf("2007-12-23 09:01:06.000000003"); +DateTimeValue dateTimeValue = DateTimeValue.from(timestamp); + +Calendar calendar = Calendar.getInstance(); +DateValue dateValueFromCal = DateValue.from(calendar); +TimeValue timeValueFromCal = TimeValue.from(calendar); +DateTimeValue dateTimeValueFromCal = DateTimeValue.from(calendar); +---- + +* `parse` which receives a `String` to represent the value (this method can throw a `ParseException`) + +[source,java] +---- +DateValue dateValue = DateValue.parse("2007-12-23"); + +// With hours and minutes only +TimeValue timeValue1 = TimeValue.parse("09:01"); +// With seconds additional +TimeValue timeValue2 = TimeValue.parse("09:01:06"); +// With nanoseconds additional +TimeValue timeValue3 = TimeValue.parse("09:01:06.000000003"); + +// With date only (so hour is midnight) +DateTimeValue dateTimeValue1 = DateTimeValue.parse("2007-12-23"); +// With date and time (hours and minutes only) +DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01"); +// With date and time (seconds additional) +DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01:06"); +// With date and time (nanoseconds additional) +DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01:06.000000003"); +---- + +* `now` which create an instance corresponding to the current moment. + +[source,java] +---- +DateValue dateValue = DateValue.now(); // The current date +TimeValue timeValue = TimeValue.now(); // The current time +DateTimeValue dateTimeValue = DateTimeValue.now(); // The current date/time +---- + +All these static methods (except for `now` method) have equivalent constructors. diff --git a/src/main/docs/modules/ROOT/pages/concepts/description.adoc b/src/main/docs/modules/ROOT/pages/concepts/description.adoc new file mode 100644 index 00000000..06b3f10a --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/description.adoc @@ -0,0 +1,21 @@ += Default description + +In assertj, it is possible to add a description with the methods of the https://www.javadoc.io/doc/org.assertj/assertj-core/latest/org/assertj/core/api/Descriptable.html[Descriptable] interface. +This description is used in the error message if the assertion fails. + +Due to the navigation, it is more complicated in assertj-db to know on which element an error is thrown. +So to help the tester, there are default descriptions. + +For example : + +* `"members table"` for an assertion on a table +* `"'select * from actor' request"` for an assertion on a request +* `"'select id, name, firstname, bi...' request"` for an assertion on a request with more text +* `"Row at index 0 of members table"` for an assertion on a row of a table +* `"Column at index 0 (column name : ID) of 'select * from members' request"` for an assertion on a column of a request +* `"Value at index 0 of Column at index 0 (column name : ID) of 'select * from members' request"` for an assertion on a value of a column of a request +* `"Value at index 0 (column name : ID) of Row at index 0 of 'select * from members' request"` for an assertion on a value of a row of a request +* `"Value at index 0 (column name : ID) of Row at end point of Change at index 0 (on table : MEMBERS and with primary key : [4]) of Changes on tables of 'sa/jdbc:h2:mem:test' source"` +for an assertion on a value of the row at end point of a change on a table + +This default description can be replaced by the choice of the tester by using the methods of https://www.javadoc.io/doc/org.assertj/assertj-core/latest/org/assertj/core/api/Descriptable.html[Descriptable]. diff --git a/src/main/docs/modules/ROOT/pages/concepts/elements.adoc b/src/main/docs/modules/ROOT/pages/concepts/elements.adoc new file mode 100644 index 00000000..b4ebdcbc --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/elements.adoc @@ -0,0 +1,529 @@ += Elements of the database + +Here the elements on which it is possible to make assertions. + +Note that, there are only 3 root elements : https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table], +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request] +and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Changes.html[Changes]. + +That means that the other elements are components or sub components of a root element. + +A root element is an element on which the assertion start (in practice, the parameter of a `assertThat(...)` method). + +[[table]] +== Table + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table] represents +a table in the database. + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table] can be constructed with the builder method `table(String name)` from +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnection.html[AssertDbConnection]. + +[source,java] +---- +// Prepare the connection +AssertDbConnection connection = ... +// Declare the "members" table by using a AssertDbConnection table builder +Table table1 = connection.table("members").build(); +---- + +For more information about table construction, see the +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.Builder.html[Table.Builder] javadoc. + +.Representation of "table1" +|==== +|ID |NAME |FIRSTNAME |SURNAME |BIRTHDATE |SIZE + +|1 |'Hewson' |'Paul David' |'Bono' |05-10-60 |1.75 +|2 |'Evans' |'David Howell' |'The Edge' |08-08-61 |1.77 +|3 |'Clayton' |'Adam' | |03-13-60 |1.78 +|4 |'Mullen' |'Larry' | |10-31-61 |1.70 +|==== + +For a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table], +it is possible to choose the columns to include and to exclude in the assertions. + +[source,java] +---- +// Get the data of the "id" and "name" columns of the "members" table +Table table2 = connection.table("members").columnsToCheck(new String[] { "id", "name" }).build(); +// Get the data of the "members" table but not of the "birthdate" column +Table table3 = connection.table("members").columnsToExclude(new String[] { "birthdate" }).build(); +// Get the data of the "name" column of the "members" table (because "id" is included and excluded) +Table table4 = connection.table("members").columnsToCheck(new String[] { "id", "name" }).columnsToExclude(new String[] { "id" }).build(); +---- + +.Representation of "table2" +|==== +|ID |NAME + +|1 |'Hewson' +|2 |'Evans' +|3 |'Clayton' +|4 |'Mullen' +|==== + +.Representation of "table3" +|==== +|ID |NAME |FIRSTNAME |SURNAME |SIZE + +|1 |'Hewson' |'Paul David' |'Bono' |1.75 +|2 |'Evans' |'David Howell' |'The Edge' |1.77 +|3 |'Clayton' |'Adam' | |1.78 +|4 |'Mullen' |'Larry' | |1.70 +|==== + +.Representation of "table4" +|==== +|NAME + +|'Hewson' +|'Evans' +|'Clayton' +|'Mullen' +|==== + +Since version <>, there are the possibility to indicate delimiters (start delimiter and end delimiter) and `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.Order.html[Order]`. + +The delimiters are useful when the table name or column name is a reserved word or contains special characters (like space or '%'). +`https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.Order.html[Order]` allows to choose the order of the `Row`. + +[source,java] +---- +// The line code below throws SQLException because "group" is SQL reserved word +Table table5 = connection.table("group").build(); +// Get the data of the "group" table by using "`" delimiter +// That generates a request +Table table6 = connection.table("group").delimiters('`', '`').build(); + +// Get the data from "members" table and order on "name" column in ascending order +Table table7 = connection.table("members").columnsToOrder(new Order[] { Order.asc("name") }).build(); +---- + +.Representation of "table6" +|==== +|ID |NAME + +|1 |'U2' +|2 |'Colplay' +|==== + +.Representation of "table7" +|==== +|ID |NAME |FIRSTNAME |SURNAME |BIRTHDATE |SIZE + +|3 |'Clayton' |'Adam' | |03-13-60 |1.78 +|2 |'Evans' |'David Howell' |'The Edge' |08-08-61 |1.77 +|1 |'Hewson' |'Paul David' |'Bono' |05-10-60 |1.75 +|4 |'Mullen' |'Larry' | |10-31-61 |1.70 +|==== + +[[request]] +== Request + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request] represents +a SQL request on the database. + +Like a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table], +a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request] +can be constructed with the builder method `request(String sql)` from +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnection.html[AssertDbConnection]. + +[source,java] +---- +// Prepare the connection +AssertDbConnection connection = ... +// Declare a request which gets the name and the firstname of the corresponding members +Request request1 = connection.request("select name, firstname from members where id = 2 or id = 3").build(); +---- + +For more information about request construction, see the +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.Builder.html[Request.Builder] javadoc. + +.Representation of "request1" +|==== +|NAME |FIRSTNAME |SURNAME + +|'Evans' |'David Howell' |'The Edge' +|'Clayton' |'Adam' | +|==== + +For a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request], +it is possible to use a simple SQL request or a SQL request with one or many parameters. + +[source,java] +---- +// Declare a request which gets the name and the firstname of the members +// and use "%e%" as a parameter +Request request2 = connection.request( + "select name, firstname from members " + + "where name like ?;") + .parameters("%e%") + .build(); +// Declare a request which gets the name and the firstname of the members +// and use "%e%" and "%Paul%" as parameters +Request request3 = connection.request( + "select name, firstname from members " + + "where name like ? and firstname like ?;") + .parameters("%e%", "%Paul%") + .build(); +---- + +.Representation of "request2" +|==== +|NAME |FIRSTNAME |SURNAME + +|'Hewson' |'Paul David' |'Bono' +|'Evans' |'David Howell' |'The Edge' +|'Mullen' |'Larry' | +|==== + +.Representation of "request3" +|==== +|NAME |FIRSTNAME |SURNAME + +|'Hewson' |'Paul David' |'Bono' +|==== + +[[changes]] +== Changes + +The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Changes.html[Changes] +are the differences of states in database between a `start point` and a `end point`. + +image::db-changes-concept.png[] + +Assume that there are these SQL statements between the start point and the end point. + +[source,java] +---- +DELETE FROM ALBUMS WHERE ID = 15; +INSERT INTO MEMBERS(ID, NAME, FIRSTNAME) VALUES(5, 'McGuiness', 'Paul'); +UPDATE MEMBERS SET SURNAME = 'Bono Vox' WHERE ID = 1; +UPDATE ALBUMS SET NAME = 'Rattle & Hum', LIVE = true WHERE ID = 8; + +---- + +[source,java] +---- +// Prepare the connection +AssertDbConnection connection = ... +// The changes can be on a DataSource or on a Source +Changes changes1 = connection.changes().build(); +// The changes can also be on a Table or on a Request +Changes changes2 = connection.changes().table(table3).build(); +Changes changes3 = connection.changes().request(request2).build(); +// The names of the columns used for the primary key are found in the metadata for a table +// but for a request it can be important to set the primary key +Changes changes4 = connection.changes().request("select name, firstname from members", r -> r.pksName("name")).build(); +---- + +For more information about changes construction, see the +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Changes.Builder.html[Changes.Builder] javadoc. + +The changes are ordered : + +* First by the type of the change : creation, modification and after deletion +* After if it is a change on a table by the name of the table +* To finish by the values of the primary key and if there are no primary key by the values of the row (for a modification) + +As indicated above, the primary key is used to order the changes. +But more important, the primary key is used to determinate which rows at the same with modifications. + +In Representation of "changes3" the modification of first row of the table become a creation and deletion. + +.Representation of "changes1" +[cols="1,2,3,4a"] +|==== +|Creation |"MEMBERS" table |`5` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !BIRTHDATE !SIZE + +!At start point !!!!!! +!At end point !5 !'McGuiness' !'Paul' !!! +!==== +|Modification |"ALBUMS" table |`8` as PK | +!==== +!!ID !RELEASE !TITLE !NUMBEROFSONGS !DURATION !LIVE + +!At start point !8 !10-10-88 !'Rattle and Hum' !17 !72:27 ! +!At end point !8 !10-10-88 !'Rattle & Hum' !17 !72:27 !true +!==== +|Modification |"MEMBERS" table |`1` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !BIRTHDATE !SIZE + +!At start point !1 !'Hewson' !'Paul David' !'Bono' !05-10-60 !1.75 +!At end point !1 !'Hewson' !'Paul David' !'Bono Vox' !05-10-60 !1.75 +!==== +|Deletion |"ALBUMS" table |`15` as PK | +!==== +!!ID !RELEASE !TITLE !NUMBEROFSONGS !DURATION !LIVE + +!At start point !15 !09-09-14 !'Songs of Innocence' !11 !48:11! +!At end point !!!!!! +!==== +|==== + +.Representation of "changes2" +[cols="1,2,3,4a"] +|==== +|Creation |"MEMBERS" table |`5` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !!!!! +!At end point !5 !'McGuiness' !'Paul' ! ! +!==== +|Modification |"MEMBERS" table |`1` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !1 !'Hewson' !'Paul David' !'Bono' !1.75 +!At end point !1 !'Hewson' !'Paul David' !'Bono Vox' !1.75 +!==== +|==== + +.Representation of "changes3" +[cols="1,2,3,4a"] +|==== +|Creation | |No PK | +!==== +!!NAME !FIRSTNAME !SURNAME + +!At start point !!! +!At end point !'Hewson' !'Paul David' !'Bono Vox' +!==== +|Creation | |No PK | +!==== +!!NAME !FIRSTNAME !SURNAME + +!At start point !!! +!At end point !'McGuiness' !'Paul' ! +!==== +|Deletion | |No PK | +!==== +!!NAME !FIRSTNAME !SURNAME + +!At start point !!! +!At end point !'Hewson' !'Paul David' !'Bono Vox' +!==== +|==== + +.Representation of "changes4" +[cols="1,2,3,4a"] +|==== +|Creation | |`'McGuiness'` as PK | +!==== +!!NAME !FIRSTNAME !SURNAME + +!At start point !!! +!At end point !'McGuiness' !'Paul' ! +!==== +|Modification | |`'Hewson'` as PK | +!==== +!!NAME !FIRSTNAME !SURNAME + +!At start point !'Hewson' !'Paul David' !'Bono' +!At end point !'Hewson' !'Paul David' !'Bono Vox' +!==== +|==== + +[[change]] +== Change + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change] +is an element of the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Changes.html[Changes]. + +Below framed in red the first https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change] +of "changes2". + +.Representation of "changes2" +[cols="1,2,3,4a"] +|==== +|Creation |"MEMBERS" table |`5` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !!!!! +!At end point !5 !'McGuiness' !'Paul' ! ! +!==== +|Modification |"MEMBERS" table |`1` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !1 !'Hewson' !'Paul David' !'Bono' !1.75 +!At end point !1 !'Hewson' !'Paul David' !'Bono Vox' !1.75 +!==== +|==== + +[[row]] +== Row + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] +can represent a row of a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table] +, of a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request] or +of a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change]. + +Below framed in red the third https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] of "table3". + +.Representation of "table3" +|==== +|ID |NAME |FIRSTNAME |SURNAME |SIZE + +|1 |'Hewson' |'Paul David' |'Bono' |1.75 +|2 |'Evans' |'David Howell' |'The Edge' |1.77 +|3 |'Clayton' |'Adam' | |1.78 +|4 |'Mullen' |'Larry' | |1.70 +|==== + +Below framed in red the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] of "request2". + +.Representation of "request2" +|==== +|NAME |FIRSTNAME |SURNAME + +|'Hewson' |'Paul David' |'Bono' +|'Evans' |'David Howell' |'The Edge' +|'Mullen' |'Larry' | +|==== + +Below framed in red the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] at end point of +the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change] +of "changes3". + +.Representation of "changes2" +[cols="1,2,3,4a"] +|==== +|Creation |"MEMBERS" table |`5` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !!!!! +!At end point !5 !'McGuiness' !'Paul' ! ! +!==== +|Modification |"MEMBERS" table |`1` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !1 !'Hewson' !'Paul David' !'Bono' !1.75 +!At end point !1 !'Hewson' !'Paul David' !'Bono Vox' !1.75 +!==== +|==== + +[[column]] +== Column + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column] +can represent a column of a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table] +, of a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request] or +of a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change]. + +Below framed in red the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column] of "table3". + +.Representation of "table3" +|==== +|ID |NAME |FIRSTNAME |SURNAME |SIZE + +|1 |'Hewson' |'Paul David' |'Bono' |1.75 +|2 |'Evans' |'David Howell' |'The Edge' |1.77 +|3 |'Clayton' |'Adam' | |1.78 +|4 |'Mullen' |'Larry' | |1.70 +|==== + +Below framed in red the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column] of "request2". + +.Representation of "request2" +|==== +|NAME |FIRSTNAME |SURNAME + +|'Hewson' |'Paul David' |'Bono' +|'Evans' |'David Howell' |'The Edge' +|'Mullen' |'Larry' | +|==== + +Below framed in red the fourth https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column] of +the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change] +of "changes3". + +.Representation of "changes2" +[cols="1,2,3,4a"] +|==== +|Creation |"MEMBERS" table |`5` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !!!!! +!At end point !5 !'McGuiness' !'Paul' ! ! +!==== +|Modification |"MEMBERS" table |`1` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !1 !'Hewson' !'Paul David' !'Bono' !1.75 +!At end point !1 !'Hewson' !'Paul David' !'Bono Vox' !1.75 +!==== +|==== + +[[value]] +== Value + +A value can be in a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] +or in a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column]. + +Below framed in red (depending of the path) : + +* the second value of the third https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] of "table3" +* the third value of the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column] of "table3" + +.Representation of "table3" +|==== +|ID |NAME |FIRSTNAME |SURNAME |SIZE + +|1 |'Hewson' |'Paul David' |'Bono' |1.75 +|2 |'Evans' |'David Howell' |'The Edge' |1.77 +|3 |'Clayton' |'Adam' | |1.78 +|4 |'Mullen' |'Larry' | |1.70 +|==== + +Below framed in red (depending of the path) : + +* the second value of the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] of "request2" +* the second value of the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column] of "request2" + +.Representation of "request2" +|==== +|NAME |FIRSTNAME |SURNAME + +|'Hewson' |'Paul David' |'Bono' +|'Evans' |'David Howell' |'The Edge' +|'Mullen' |'Larry' | +|==== + +Below framed in red (depending of the path) : + +* the fourth value of the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Row.html[Row] at end point of +the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change] +of "changes2" +* the value at end point of the fourth https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Column.html[Column] of +the second https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Change.html[Change] +of "changes2" + +.Representation of "changes2" +[cols="1,2,3,4a"] +|==== +|Creation |"MEMBERS" table |`5` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !!!!! +!At end point !5 !'McGuiness' !'Paul' ! ! +!==== +|Modification |"MEMBERS" table |`1` as PK | +!==== +!!ID !NAME !FIRSTNAME !SURNAME !SIZE + +!At start point !1 !'Hewson' !'Paul David' !'Bono' !1.75 +!At end point !1 !'Hewson' !'Paul David' !'Bono Vox' !1.75 +!==== +|==== diff --git a/src/main/docs/modules/ROOT/pages/concepts/index.adoc b/src/main/docs/modules/ROOT/pages/concepts/index.adoc new file mode 100644 index 00000000..bf0e69c5 --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/index.adoc @@ -0,0 +1,42 @@ += Concepts + +For the examples below, suppose that the database contains these three tables : + +.MEMBERS +|==== +|ID |NAME |FIRSTNAME |SURNAME |BIRTHDATE |SIZE + +|1 |'Hewson' |'Paul David' |'Bono' |05-10-60 |1.75 +|2 |'Evans' |'David Howell' |'The Edge' |08-08-61 |1.77 +|3 |'Clayton' |'Adam' | |03-13-60 |1.78 +|4 |'Mullen' |'Larry' | |10-31-61 |1.70 +|==== + +.ALBUMS +|==== +|ID |RELEASE |TITLE |NUMBEROFSONGS |DURATION |LIVE + +|1 |10-20-80 |'Boy' |12 |42:17 | +|2 |10-12-81 |'October' |11 |41:08 | +|3 |02-28-83 |'War' |10 |42:07 | +|4 |11-07-83 |'Under a Blood Red Sky' |8 |33:25 |true +|5 |10-01-84 |'The Unforgettable Fire' |10 |42:42 | +|6 |06-10-85 |'Wide Awake in America' |4 |20:30 |true +|7 |03-09-87 |'The Joshua Tree' |11 |50:11 | +|8 |10-10-88 |'Rattle and Hum' |17 |72:27 | +|9 |11-18-91 |'Achtung Baby' |12 |55:23 | +|10 |07-06-93 |'Zooropa' |10 |51:15 | +|11 |03-03-97 |'Pop' |12 |60:08 | +|12 |10-30-00 |'All That You Can't Leave Behind' |11 |49:23 | +|13 |11-22-04 |'How to Dismantle an Atomic Bomb' |11 |49:08 | +|14 |03-02-09 |'No Line on the Horizon' |11 |53:44 | +|15 |09-09-14 |'Songs of Innocence' |11 |48:11 | +|==== + +.GROUP +|==== +|ID |NAME + +|1 |'U2' +|2 |'Coldplay' +|==== diff --git a/src/main/docs/modules/ROOT/pages/concepts/letter-case.adoc b/src/main/docs/modules/ROOT/pages/concepts/letter-case.adoc new file mode 100644 index 00000000..766ba1fa --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/letter-case.adoc @@ -0,0 +1,88 @@ += Letter Case of the database + +Databases have different letter cases for the name of the elements. +For example, the name of the table can be upper case either the name is inputted in upper case or not. So this concept (and feature too) is here to manage these shades. + +It is possible to declare a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] +with a <>. + +The concept of https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] is composed of https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversion.html[CaseConversion] and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparison.html[CaseComparison]. + +== CaseConversion + +The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversion.html[CaseConversion] is used when getting a name with letter case from database : a table name, a column name or a primary key name. + +There are three conversions modes : https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversions.html#UPPER[UPPER] which converts to upper case (`"Name"` becomes `"NAME"`), https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversions.html#LOWER[LOWER] which converts to lower case (`"Name"` becomes `"name"`) and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversions.html#NO[NO] which keeps the case (`"Name"` remains `"Name"`). + +Each name (table, column and primary key) got from the database is converted using a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversion.html[CaseConversion]. + +== CaseComparison + +The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparison.html[CaseComparison] is used when comparing something with letter case from database or with a parameter. + +There are two comparison modes : https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparisons.html#IGNORE[IGNORE] which compares `String`s by ignoring the case (`"Name"` is considered equal to `"NAME"`) and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparisons.html#STRICT[STRICT] which compares `String`s strictly (`"Name"` is considered different from `"NAME"`). + +During navigation (e.g. from table to column) and assertion (e.g. on column name), the name are compared using a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparison.html[CaseComparison]. + +== LetterCase + +A https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] is created with the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html#getLetterCase-org.assertj.db.type.lettercase.CaseConversion-org.assertj.db.type.lettercase.CaseComparison-[getLetterCase] +static method which has a +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversion.html[CaseConversion] and a +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparison.html[CaseComparison] as parameters. + +[source,java] +---- +LetterCase letterCase = LetterCase.getLetterCase(CaseConversions.NO, CaseComparisons.IGNORE); +---- + +In AssertJ-DB, there are three different uses of a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] : +the table name, the column name and the primary key name. +That is the reason why the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnection.html[AssertDbConnection] +have three https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] parameters. + +The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] on the tables is used : + +* to convert the table name : when a name is got from the database like for the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table] +instantiation or for the table with changes found with https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Changes.html[Changes]. +* to compare the table name : for the instantiation when the table is search in the database for https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table], +for navigation (e.g. from changes to a change on a table) or for a assertion (like https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnDataType.html#isOnTable-java.lang.String-[isOnTable(String name)]). + +The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] on the columns is used : + +* to convert the column name : when a column name is got from the database for a table or a request +* to compare the column name : for the navigation (e.g. from a table to a column) or for a assertion (like https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnName.html#hasColumnName-java.lang.String-[hasColumnName(String columnName)]). + +The https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] on the primary keys is used : + +* to convert the primary key name : when a primary key name is got from the database for a table +* to compare the primary key name : for a assertion (like https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnPrimaryKey.html#hasPksNames-java.lang.String...-[hasPksNames(String... names)]). + +The default settings for https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html[LetterCase] in +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/AssertDbConnection.html[AssertDbConnection] are : + +* https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversions.html#NO[NO] conversion +and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparisons.html#IGNORE[IGNORE] comparison for table names +* https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversions.html#UPPER[UPPER] conversion +and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparisons.html#IGNORE[IGNORE] comparison for the column and primary key name + +In this example, the two connections are equivalent : + +[source,java] +---- +AssertDbConnection jdbcConnection = AssertDbConnectionFactory.of("jdbc:h2:mem:test", "sa", "").create(); +Table table = jdbcConnection.table("members").build(); + +LetterCase tableLetterCase = LetterCase.getLetterCase(CaseConversions.NO, CaseComparisons.IGNORE); +LetterCase columnLetterCase = LetterCase.getLetterCase(CaseConversions.UPPER, CaseComparisons.IGNORE); +LetterCase pkLetterCase = LetterCase.getLetterCase(CaseConversions.UPPER, CaseComparisons.IGNORE); +AssertDbConnection connectionWithLC = AssertDbConnectionFactory.of("jdbc:h2:mem:test", "sa", "") + .letterCase(tableLetterCase, columnLetterCase, pkLetterCase) + .create(); +Table tableWithLC = connectionWithLC.table("members").build(); +---- + +Note that the letter case is extensible because the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/LetterCase.html#getLetterCase-org.assertj.db.type.lettercase.CaseConversion-org.assertj.db.type.lettercase.CaseComparison-[getLetterCase] +static method's parameters are instances of the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseConversion.html[CaseConversion] +and the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/lettercase/CaseComparison.html[CaseComparison] interfaces. +So this is not limited to the implementations in the corresponding enumerations. diff --git a/src/main/docs/modules/ROOT/pages/concepts/navigation.adoc b/src/main/docs/modules/ROOT/pages/concepts/navigation.adoc new file mode 100644 index 00000000..97658b64 --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/navigation.adoc @@ -0,0 +1,79 @@ += Navigation + +The navigation offers the ability to chain assertions at different levels and instructions to go inside the sub-elements and return to root element. + +There are examples of the navigation in {assertj-examples-repo}/blob/main/assertions-examples/src/test/java/org/assertj/examples/db/NavigationExamples.java[NavigationExamples.java] + +[[tableorrequestasroot]] +== With a Table or a Request as root + +The `assertThat(...)` static method of `org.assertj.db.api.Assertions` allows to create a root assertion on a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table]. + +[source,java] +---- +import static org.assertj.db.api.Assertions.assertThat; + +assertThat(table)... +---- + +or on a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request]. + +[source,java] +---- +import static org.assertj.db.api.Assertions.assertThat; + +assertThat(request)... +---- + +From these root assertions, it is possible to navigate to the sub elements and return to the root element as in the picture below. + +[ditaa, target="db-navigation-with-table-or-request", shadows=false, transparent=true] +.... + origin + instantiate+-----------+<-----------=+----------------------+ + +--------->|On a Column| instantiate |On a Value Of a Column| + | +-----+-----+=----------->+----------------------+ + : origin: ++----------------+------+<--------+ +|On a Table Or a Request| ++----------------+------+<--------+ + : origin: origin + | +-----+--+<-----------=+-------------------+ + +--------->|On a Row| instantiate |On a Value Of a Row| + instantiate+--------+=----------->+-------------------+ +.... + +More details on this concept in assertj-db-features-highlight.html#tableorrequestasroot[feature highlight]. + +== With Changes as root + +The `assertThat(...)` static method of `org.assertj.db.api.Assertions` +allows to create a root assertion on https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Changes.html[Changes]. + +[source,java] +---- +import static org.assertj.db.api.Assertions.assertThat; + +assertThat(changes)... +---- + +From this root assertion, it is possible to navigate to the sub elements and return to the root element as in the picture below. + +[ditaa, target="db-navigation-with-changes", shadows=false, transparent=true] +.... + origin + instantiate+-----------+<-----------=+----------------------+ + +--------->|On a Column| instantiate |On a Value Of a Column| + | +-----+-----+=----------->+----------------------+ + origin : origin: ++-----------+<=-----------+-----+-----+<---------+ +|On Changes | instantiate |On a Change| ++-----------+=----------->+-----+-----+<---------+ + : origin: origin + | +-----+--+<-----------=+-------------------+ + +--------->|On a Row| instantiate |On a Value Of a Row| + instantiate+--------+=----------->+-------------------+ +.... + + +More details on this concept in <>. diff --git a/src/main/docs/modules/ROOT/pages/concepts/output.adoc b/src/main/docs/modules/ROOT/pages/concepts/output.adoc new file mode 100644 index 00000000..e61dd0af --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/output.adoc @@ -0,0 +1,70 @@ += Output + +It can be interesting to view the values on which an assertion is made (for example for debugging). The output allows that. + +This is a simple example : + +[source,java] +---- +import static org.assertj.db.output.Outputs.output; + +Table table = connection.table("members"); + +// Output the content of the table in the console +output(table).toConsole(); +---- + +These lines give the result below : + +[source,java] +---- +[MEMBERS table] +|-----------|---------|-----------|-----------|--------------|-----------|-----------|-----------| +| | | * | | | | | | +| | PRIMARY | ID | NAME | FIRSTNAME | SURNAME | BIRTHDATE | SIZE | +| | KEY | (NUMBER) | (TEXT) | (TEXT) | (TEXT) | (DATE) | (NUMBER) | +| | | Index : 0 | Index : 1 | Index : 2 | Index : 3 | Index : 4 | Index : 5 | +|-----------|---------|-----------|-----------|--------------|-----------|-----------|-----------| +| Index : 0 | 1 | 1 | Hewson | Paul David | Bono | 05-10-60 | 1.75 | +| Index : 1 | 2 | 2 | Evans | David Howell | The Edge | 08-08-61 | 1.77 | +| Index : 2 | 3 | 3 | Clayton | Adam | | 03-13-60 | 1.78 | +| Index : 4 | 4 | 4 | Mullen | Larry | | 10-31-61 | 1.70 | +|-----------|---------|-----------|-----------|--------------|-----------|-----------|-----------| +---- + +In the example above, the output is in plain text in the console. It is possible to change the type of the output and the destination. + +== Type of output + +There are two outputs already implemented : + +* https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/impl/OutputType.html#PLAIN[PLAIN] : shown in the example above (the default output type) +* https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/impl/OutputType.html#HTML[HTML] : which represents the result as an HTML document + +[source,java] +---- +// Change the output of the table to be HTML +output(table).withType(OutputType.HTML).....; +---- + +Note that the type of output is extensible because the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/AbstractOutputter.html#withType-org.assertj.db.output.impl.Output-[withType(Output outputType)] method's parameter is an instance of the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/impl/Output.html[Output] interface. +So this is not limited to the implementations in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/impl/OutputType.html[OutputType] enum. + +== Destination + +The destination is the way to print the display. There are three destinations : + +* the console (with the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/AbstractOutputter.html#toConsole--[toConsole()] method) +* a file (with the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/AbstractOutputter.html#toFile-java.lang.String-[toFile(String fileName)] method) +* a stream (with the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/output/AbstractOutputter.html#toStream-java.io.OutputStream-[toStream(OutputStream outputStream)] method) + +Note that with this last method the possibilities of destination are really flexible. + +These three methods are fluent. In this short example, the output is a plain text representation in the console and a html output in a file : + +[source,java] +---- +// Display the content of the table with plain text in the console +// and with HTML output in the file +output(table).toConsole().withType(OutputType.HTML).toFile("test.html"); +---- diff --git a/src/main/docs/modules/ROOT/pages/concepts/types.adoc b/src/main/docs/modules/ROOT/pages/concepts/types.adoc new file mode 100644 index 00000000..39d7d8c2 --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/concepts/types.adoc @@ -0,0 +1,51 @@ += Type + +== Data Type + +As see above there are three root elements of database, but only https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table] and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request] are data elements. +All the possible types of data are contained in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/DataType.html[DataType] enumeration. + +The type of the data can be : + +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/DataType.html#TABLE[TABLE]` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/DataType.html#REQUEST[REQUEST]` + +[[change_type]] +== Change Type + +The change can be a creation, a modification or a deletion. +All the possible types of change are contained in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ChangeType.html[ChangeType] enumeration. + +The type of the change depends of operation on database : + +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ChangeType.html#CREATION[CREATION]` for a `insert` sql request +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ChangeType.html#MODIFICATION[MODIFICATION]` for a `update` sql request +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ChangeType.html#DELETION[DELETION]` for a `delete` sql request + +== Value Type + +The value can be a date, a boolean or a text for example. +All the possible types of value are contained in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html[ValueType] enumeration. + +The type of the value depends of class of the object given by `java.sql` when the data are got from database : + +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#BYTES[BYTES]` for a array of bytes (`byte[]`) +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#BOOLEAN[BOOLEAN]` for a `java.lang.Boolean` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#TEXT[TEXT]` for a `java.lang.String` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#DATE[DATE]` for a `java.sql.Date` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#TIME[TIME]` for a `java.sql.Time` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#DATE_TIME[DATE_TIME]` for a `java.sql.Timestamp` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#UUID[UUID]` for a `java.util.UUID` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#NUMBER[NUMBER]` for a `java.lang.Byte`, +`java.lang.Short`, `java.lang.Integer`, `java.lang.Long`, `java.lang.Double`, `java.lang.Float` or `java.math.BigDecimal` +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/ValueType.html#NOT_IDENTIFIED[NOT_IDENTIFIED]` for other cases (for example when the value is `null`) + +== Order Type + +The order can be a ascending or descending. +All the possible types of order are contained in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.Order.OrderType.html[Table.Order.OrderType] enumeration. + +The type of the order can be : + +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.Order.OrderType.html#ASC[ASC]` for an ascending order +* `https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.Order.OrderType.html#DESC[DESC]` for a descending order diff --git a/src/main/docs/modules/ROOT/pages/features/assertions.adoc b/src/main/docs/modules/ROOT/pages/features/assertions.adoc new file mode 100644 index 00000000..a6c207ed --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/features/assertions.adoc @@ -0,0 +1,785 @@ += Assertions + +== On the type of change + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnChangeType.html[AssertOnChangeType] interface. + +These assertions allow to verify the type of change (the concept of change of type is described xref::concepts/types.adoc#change_type[here]). + +[source,java] +---- +// Verify that the first change is a change of creation +assertThat(changes).change().isOfType(ChangeType.CREATION); +---- + +There are specific assertion methods for each type of change. For example, the assertion below is equivalent to the one above + +[source,java] +---- +assertThat(changes).change().isCreation(); +---- + +== On the equality with the values of a column + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnEquality.html[AssertOnColumnEquality] +and the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnOfChangeEquality.html[AssertOnColumnOfChangeEquality] interfaces. + +These assertion allow to verify the values of a column (the column of a table, of a request or of a change). + +=== With Boolean + +[source,java] +---- +// Verify that the values of the column "live" of the request +// was equal to true, to false and after to true +assertThat(request).column("live").hasValues(true, false, true); +// Verify that the value of the first column of the first change +// was false at start point and is true at end point +assertThat(changes).change().column().hasValues(false, true); +// Verify that the value of the third column of the first change +// is not modified and is true +assertThat(changes).change().column(2).hasValues(true); +---- + +=== With Bytes + +[source,java] +---- +// Get bytes from a file and from a resource in the classpath +byte[] bytesFromFile = Assertions.bytesContentOf(file); +byte[] bytesFromClassPath = Assertions.bytesContentFromClassPathOf(resource); +// Verify that the values of the second column of the request +// was equal to the bytes from the file, to null and to bytes from the resource +assertThat(request).column(1).hasValues(bytesFromFile, null, bytesFromClassPath); +// Verify that the value of the first column of the first change +// was equal to bytes from the file at start point and to bytes from the resource at end point +assertThat(changes).change().column().hasValues(bytesFromFile, bytesFromClassPath); +---- + +=== With Number + +[source,java] +---- +// Verify that the values of the first column of the table +// was equal to 5.9, 4 and 15000 +assertThat(table).column().hasValues(5.9, 4, new BigInteger("15000")); +// Verify that the value of the first column of the first change +// is not modified and is equal to 5 +assertThat(changes).change().column().hasValues(5); +---- + +=== With Date + +[source,java] +---- +// Verify that the values of the first column of the table +// was equal to December 23rd 2007 and May 19th 1975 +assertThat(table).column() + .hasValues(LocalDate.of(2007, 12, 23), + LocalDate.of(1975, 5, 19)); +// Verify that the value of the first column of the first change +// was equal December 23rd 2007 at start point +// and is equal to May 19th 1975 at end point +assertThat(changes).change().column() + .hasValues(LocalDate.parse("2007-12-23"), + LocalDate.parse("1975-05-19")); +---- + +=== With Time + +[source,java] +---- +// Verify that the values of the first column of the table +// was equal to 09:01am and 05:30:50pm +assertThat(table).column() + .hasValues(LocalTime.of(9, 1), + LocalTime.of(17, 30, 50)); +// Verify that the value of the first column of the first change +// was equal to 09:01am at start point +// and is equal to 05:30:50pm at end point +assertThat(changes).change().column() + .hasValues(LocalTime.parse("09:01"), + LocalTime.parse("17:30:50")); +---- + +=== With Date/Time + +[source,java] +---- +// Verify that the values of the first column of the table +// was equal to December 23rd 2007 09:01am and May 19th 1975 +assertThat(table).column() + .hasValues(LocalDateTime.of(LocalDate.of(2007, 12, 23), + LocalTime.parse("09:01")), + LocalDateTime.of(LocalDate.of(1975, 5, 19), + LocalTime.MIDNIGHT)); +// Verify that the value of the first column of the first change +// was equal December 23rd 2007 09:01am at start point +// and is equal to May 19th 1975 at end point +assertThat(changes).change().column() + .hasValues(LocalDateTime.parse("2007-12-23T09:01"), + LocalDateTime.parse("1975-05-19T00:00")); +---- + +=== With String + +[source,java] +---- +// Verify that values are equal to texts +assertThat(table).column("name") + .hasValues("Hewson", + "Evans", + "Clayton", + "Mullen"); +// Verify that the value of the column "size" of the first change of modification +// is not modified and is equal to 1.75 by parsing +assertThat(changes).changeOfModification().column("size") + .hasValues("1.75"); +// Verify that values are equal to dates, times or dates/times by parsing +assertThat(table).column() + .hasValues("2007-12-23T09:01"), + "1975-05-19"); +---- + +=== With UUID + +[source,java] +---- +// Verify that the values of the first column of the table +// was equal to 30B443AE-C0C9-4790-9BEC-CE1380808435, 0E2A1269-EFF0-4233-B87B-B53E8B6F164D +// and 2B0D1BDD-909E-4362-BA10-C930BA82718D +assertThat(table).column().hasValues(UUID.fromString("30B443AE-C0C9-4790-9BEC-CE1380808435"), + UUID.fromString("0E2A1269-EFF0-4233-B87B-B53E8B6F164D"), + UUID.fromString("2B0D1BDD-909E-4362-BA10-C930BA82718D")); +// Verify that the value of the first column of the first change +// is not modified and is equal to 399FFFCA-7874-4225-9903-E227C4E9DCC1 +assertThat(changes).change() + .column().hasValues(UUID.fromString("399FFFCA-7874-4225-9903-E227C4E9DCC1")); +---- + +=== With Character + +[source,java] +---- +// Verify that the values of the first column of the table +// was equal to 'T', 'e', 's' and 't' +assertThat(table).column().hasValues('T', 'e', 's', 't'); +// Verify that the value of the first column of the first change +// is not modified and is equal to 'T' +assertThat(changes).change().column().hasValues('T'); +---- + +== On the name of a column + +This assertion is described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnName.html[AssertOnColumnName] interface. + +This assertion allows to verify the name of a column (the column of a table, of a request or of a change). + +[source,java] +---- +// Verify that the fifth column of the table is called "firstname" +assertThat(table).column(4).hasColumnName("firstname"); +// Verify that the third value of the second row of the request is in a column called "name" +assertThat(request).row(1).value(2).hasColumnName("name"); +// Verify that the first column of the first change is called "id" +assertThat(changes).change().column().hasColumnName("id"); +---- + +== On the nullity of the values of a column + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnNullity.html[AssertOnColumnNullity] interface. + +These assertion allows to verify the nullity of the values of a column (the column of a table or of a request). + +[source,java] +---- +// Verify that the fifth column of the table has only null values +assertThat(table).column(4).hasOnlyNullValues(); +// Verify that the column "name" has only not null values +assertThat(request).column("name").hasOnlyNotNullValues(); +---- + +== On the nullity of the values of a row + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnRowNullity.html[AssertOnRowNullity] interface. + +These assertion allows to verify the nullity of the values of a row (the row of a table or of a request). + +[source,java] +---- +// Verify that the fifth row of the table has only not null values +assertThat(table).row(4).hasOnlyNotNullValues(); +// Verify that the first column has only not null values +assertThat(request).row().hasOnlyNotNullValues(); +---- + +== On the type of column + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnType.html[AssertOnColumnType] interface. + +These assertions allow to verify the type of the values of a column (a column from a table, from a request or from a change). + +[source,java] +---- +// Verify that the values of the column called "firstname" +// of the table are a text (null values are considered as wrong) +assertThat(table).column("firstname").isOfType(ValueType.TEXT, false); +// The same verification (with the specific method) +// on the third column of the request +assertThat(request).column(2).isText(false); +// Now the same verification again but with a lenience with null values +// (the null values are not considered as wrong) +assertThat(request).column(2).isText(true); +// Verify that the values of the first column +// of the first change is either a date or a number +assertThat(changes).change().column() + .isOfAnyOfTypes(ValueType.DATE, ValueType.NUMBER); +---- + +== On the class of column + +This assertion is described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnClass.html[AssertOnColumnClass] interface. + +This assertion allows to verify the class of the values of a column (a column from a table, from a request or from a change). + +[source,java] +---- +// Verify that the values of the column called "firstname" +// of the table are a String (null values are considered as wrong) +assertThat(table).column("firstname").isOfClass(String.class, false); +// Verify that the values of the first column +// of the first change is a Locale (null values are considered as right) +assertThat(changes).change().column().isOfClass(Locale.class, true); +---- + +== On the content of column + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnColumnContent.html[AssertOnColumnContent] interface. + +These assertions allow to verify the content of a column (a column from a table or from a request). + +[source,java] +---- +// Verify that the content of the column called "name" +assertThat(table).column("name").containsValues("Hewson", + "Evans", + "Clayton", + "Mullen"); +// This second assertion is equivalent because the order of the values is not important +assertThat(table).column("name").containsValues("Evans", + "Clayton", + "Hewson", + "Mullen"); + +---- + +== On the type of data + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnDataType.html[AssertOnDataType] interface. + +These assertions allow to verify the type of the date on which is a change. + +[source,java] +---- +// Verify that the change is on a table +assertThat(changes).change().isOnDataType(DataType.TABLE); +// The same verification (with the specific method) +assertThat(changes).change().isOnTable(); +// Verify that the change is on the "members" table +assertThat(changes).change().isOnTable("members"); +---- + +== On the modified columns in a change + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnModifiedColumn.html[AssertOnModifiedColumn] +and the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnModifiedColumns.html[AssertOnModifiedColumns] interfaces. + +These assertions allow to verify if a column of a change have been modified between the start point and the end point (see the xref:concepts/elements.adoc#changes[concept of changes]). + +[source,java] +---- +// Verify that first column of the change is not modified +// and the second column is modified +assertThat(changes).change().column().isNotModified().column().isModified(); +// Verify that there are 2 modified columns in the change +assertThat(changes).change().hasNumberOfModifiedColumns(2); +// Verify that the modified column in change are at index 1 and 2 +assertThat(changes).change().hasModifiedColumns(1, 2); +// Verify that the modified column in change are "name" and "firstname" +assertThat(changes).change().hasModifiedColumns("name", "firstname"); +---- + +Compare the number of modified columns between the start point and the end point. + +[source,java] +---- +// Verify that the number of modified columns in the first change is more than 5 +assertThat(changes).change().hasNumberOfModifiedColumnsGreaterThan(5); +// Verify that the number of modified columns in the first change is at least 5 +assertThat(changes).change().hasNumberOfModifiedColumnsGreaterThanOrEqualTo(5); +// Verify that the number of modified columns in the first change is less than 6 +assertThat(changes).change().hasNumberOfModifiedColumnsLessThan(6); +// Verify that the number of modified columns in the first change is at most 6 +assertThat(changes).change().hasNumberOfModifiedColumnsLessThanOrEqualTo(6); +---- + +== On the number of changes + +This assertion is described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnNumberOfChanges.html[AssertOnNumberOfChanges] interface. + +This assertion allows to verify the number of changes. + +[source,java] +---- +// Verify that there are 4 changes +assertThat(changes).hasNumberOfChanges(4); +---- + +Compare the number of changes between the start point and the end point. + +[source,java] +---- +// Verify that the number of changes is more than 5 +assertThat(changes).hasNumberOfChangesGreaterThan(5); +// Verify that the number of changes is at least 5 +assertThat(changes).hasNumberOfChangesGreaterThanOrEqualTo(5); +// Verify that the number of changes is less than 6 +assertThat(changes).hasNumberOfChangesLessThan(6); +// Verify that the number of changes is at most 6 +assertThat(changes).hasNumberOfChangesLessThanOrEqualTo(6); +---- + +== On the number of columns + +This assertion is described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnNumberOfColumns.html[AssertOnNumberOfColumns] interface. + +This assertion allows to verify the number of columns (columns from a table, from a request or from a change). + +[source,java] +---- +// Verify that there are 6 columns in the table +assertThat(table).hasNumberOfColumns(6); +// Verify that there are 4 columns in the change +assertThat(changes).change().hasNumberOfColumns(4); +---- + +Compare the number of columns. + +[source,java] +---- +// Verify that the number of columns is more than 5 +assertThat(table).hasNumberOfColumnsGreaterThan(5); +// Verify that the number of columns is at least 5 +assertThat(request).hasNumberOfColumnsGreaterThanOrEqualTo(5); +// Verify that the number of columns is less than 6 +assertThat(changes).hasNumberOfColumnsLessThan(6); +// Verify that the number of columns is at most 6 +assertThat(changes).hasNumberOfColumnsLessThanOrEqualTo(6); +---- + +== On the number of rows + +This assertion is described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnNumberOfRows.html[AssertOnNumberOfRows] interface. + +This assertion allows to verify the number of rows (rows from a table or from a request). + +[source,java] +---- +// Verify that there are 7 rows in the table +assertThat(table).hasNumberOfRows(7); +---- + +Compare the number of rows. + +[source,java] +---- +// Verify that the number of rows is more than 5 +assertThat(table).hasNumberOfRowsGreaterThan(5); +// Verify that the number of rows is at least 5 +assertThat(request).hasNumberOfRowsGreaterThanOrEqualTo(5); +// Verify that the number of rows is less than 6 +assertThat(changes).hasNumberOfRowsLessThan(6); +// Verify that the number of rows is at most 6 +assertThat(changes).hasNumberOfRowsLessThanOrEqualTo(6); +---- + +Verify if rows are empty (equivalent to `hasNumberOfRows(0)`). + +[source,java] +---- +// Verify that the table are empty +assertThat(table).isEmpty(); +---- + +== On the primary keys + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnPrimaryKey.html[AssertOnPrimaryKey] interface. + +These assertions allow to verify the names and the values of the columns which compose the primary keys of the rows from a change. + +[source,java] +---- +// Verify that the columns of the primary keys are "id" and "name" +assertThat(changes).change().hasPksNames("id", "name"); +// Verify that the values of the primary keys are 1 and "HEWSON" +assertThat(changes).change().hasPksValues(1, "HEWSON"); +---- + +== On the equality with the values of a row + +This assertion is described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnRowEquality.html[AssertOnRowEquality] interface. + +This assertion allow to verify the values of a row (the row of a table, of a request or of a change). + +[source,java] +---- +// Verify the values of the row at index 1 +assertThat(table).row(1) + .hasValues(2, + "Evans", + "David Howell", + "The Edge", + DateValue.of(1961, 8, 8), + 1.77); +// Verify the values of the row at end point +assertThat(changes).change().rowAtEndPoint() + .hasValues(5, + "McGuiness", + "Paul", + null, + "1951-06-17", + null); +---- + +== On the existence of a row in a change + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnRowOfChangeExistence.html[AssertOnRowOfChangeExistence] interface. + +These assertions allow to verify that the row at start point or at end point of a change exists or not (for a creation, the row do not exist at start point and for a deletion it is the contrary : the row do not exist at end point). + +[source,java] +---- +// Verify that row at start point exists +assertThat(changes).change().rowAtStartPoint().exists(); +// Verify that the row at end point do not exist +assertThat(changes).change().rowAtEndPoint().doesNotExist(); +---- + +== On the chronology of a value + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueChronology.html[AssertOnValueChronology] interface. + +These assertions allow to compare a value (the value of a table, of a request or of a change) to a date, a time or a date/time. + +[source,java] +---- +// Compare the value with a date +assertThat(table).row(1).value("birthdate") + .isAfter(DateValue.of(1950, 8, 8)); +// Verify the value is between two dates/times +assertThat(changes).change().column("release").valueAtEndPoint() + .isAfterOrEqualTo(DateTimeValue.parse("2014-09-08T23:30")) + .isBeforeOrEqualTo(DateTimeValue.parse("2014-09-09T05:30")); +---- + +== On the comparison with a value + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueComparison.html[AssertOnValueComparison] interface. + +These assertions allow to compare a value (the value of a table, of a request or of a change) to a number. + +[source,java] +---- +// Compare the value with a number +assertThat(table).row(1).value("size") + .isGreaterThan(1.5); +// Verify the value is between two numbers +assertThat(changes).change().column("size").valueAtEndPoint() + .isGreaterThanOrEqualTo(1.7) + .isLessThanOrEqualTo(1.8); +---- + +== On the closeness of a value + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueCloseness.html[AssertOnValueCloseness] interface. + +These assertions allow to verify if a value (the value of a table, of a request or of a change) is close to another. + +[source,java] +---- +// Verify if the value is close to 2 with a tolerance of 0.5 +// So the values between 1.5 and 2.5 are right +assertThat(table).row(1).value("size") + .isCloseTo(2, 0.5); +// Verify the value is close to 05-10-1960 with a tolerance of two days +assertThat(changes).change().column("birth").valueAtEndPoint() + .isCloseTo(DateValue(1960, 5, 10), + DateValue(0, 0, 2)); +---- + +== On the equality with a value + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueEquality.html[AssertOnValueEquality] interface. + +These assertion allow to verify that a value (the value of a table, of a request or of a change) is equal to another value (in parameter). + +=== With Boolean + +[source,java] +---- +// Verify that the value is equal to true +assertThat(table).row(3).value("live").isEqualTo(true); +// Do the same thing with the specific method +assertThat(table).row(3).value("live").isTrue(); +---- + +=== With Bytes + +[source,java] +---- +// Get bytes from a file +byte[] bytesFromFile = Assertions.bytesContentOf(file); +// Verify that the value at end point of the first column of the first change +// is equal to bytes from the file +assertThat(changes).change().column().valueAtStartPoint().isEqualTo(bytesFromFile); +---- + +=== With Number + +[source,java] +---- +// Verify that the first value is equal to 1.77, +// the second is equal to 50 and the last is equal to zero +assertThat(request).column("size").value().isEqualTo(1.77) + .value().isEqualTo(50) + .value().isEqualTo(0).isZero(); +---- + +=== With Date + +[source,java] +---- +// Verify that values are equal to dates +assertThat(changes).changeOfCreation() + .rowAtEndPoint() + .value("birthdate") + .isEqualTo(LocalDate.of(1951, 6, 17)) + .changeOfModification() + .column("birthdate") + .isEqualTo() + .isNotEqualTo(LocalDate.parse("1960-05-10")) + .valueAtEndPoint() + .isEqualTo(LocalDate.of(1960, 5, 10)); +---- + +=== With Time + +[source,java] +---- +// Verify that the value is equal to a time +assertThat(table).row().value("duration").isEqualTo(LocalTime.of(9, 1)); +---- + +=== With Date/Time + +[source,java] +---- +// Verify that the value is equal to a date/time +assertThat(request).column().value() + .isEqualTo(LocalDateTime.of(2007, 12, 23,9, 1, 0)) + .isEqualTo(LocalDateTime.parse("2007-12-23T09:01")); +---- + +=== With String + +[source,java] +---- +// Verify that the values are equal to numbers, texts and dates +assertThat(table).row().value().isEqualTo("1") + .value().isEqualTo("Hewson") + .value().isEqualTo("Paul David") + .value().isEqualTo("Bono") + .value().isEqualTo("1960-05-10") + .value().isEqualTo("1.75"); +---- + +=== With UUID + +[source,java] +---- +// Verify that the values are equal to UUID +assertThat(table).column().value().isEqualTo(UUID.fromString("30B443AE-C0C9-4790-9BEC-CE1380808435")) + .value().isEqualTo(UUID.fromString("0E2A1269-EFF0-4233-B87B-B53E8B6F164D")) + .value().isEqualTo(UUID.fromString("2B0D1BDD-909E-4362-BA10-C930BA82718D")); +---- + +=== With Character + +[source,java] +---- +// Verify that the values are equal to Character +assertThat(table).column().value().isEqualTo('T') + .value().isEqualTo('e') + .value().isEqualTo('s') + .value().isEqualTo('t'); +---- + +== On the non equality with a value + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueNonEquality.html[AssertOnValueNonEquality] interface. + +These assertion allow to verify that a value (the value of a table, of a request or of a change) is not equal to another value (in parameter). + +=== With Boolean + +[source,java] +---- +// Verify that the values (values "live" in the row at index 3 and index 5) +// are not equal to false +assertThat(table).row(3).value("live").isNotEqualTo(false) + .row(5).value("live").isNotEqualTo(false); +---- + +=== With Bytes + +[source,java] +---- +// Get bytes from a resource in the classpath +byte[] bytesFromClassPath = Assertions.bytesContentFromClassPathOf(resource); +// Verify that the value at end point of the first column of the first change +// is not equal to bytes from the resource +assertThat(changes).change().column().valueAtStartPoint().isNotEqualTo(bytesFromClassPath); +---- + +=== With Number + +[source,java] +---- +// Verify that the first value is not equal to 1.78, +// the second is not equal to 55 and the last is not equal to 15 +assertThat(request).column("size").value().isNotEqualTo(1.78) + .value().isNotEqualTo(55) + .value().isNotEqualTo(15); +---- + +=== With Date + +[source,java] +---- +// Verify that values are not equal to dates +assertThat(changes).changeOfCreation() + .rowAtEndPoint() + .value("birthdate") + .isNotEqualTo(LocalDate.of(1951, 6, 17)) + .changeOfModification() + .column("birthdate") + .valueAtStartPoint() + .isNotEqualTo(LocalDate.parse("1960-05-10")) + .valueAtEndPoint() + .isNotEqualTo(LocalDate.of(1960, 5, 10)); +---- + +=== With Time + +[source,java] +---- +// Verify that the value is equal to a time +assertThat(table).row().value("duration").isNotEqualTo(LocalTime.of(9, 1)); +---- + +=== With Date/Time + +[source,java] +---- +// Verify that the value is not equal to a date/time +assertThat(request).column().value() + .isNotEqualTo(LocalDateTime.of(2015, 5, 26,22, 46))) + .isNotEqualTo(LocalDateTime.parse("2015-05-26T22:46")); +---- + +=== With String + +[source,java] +---- +// Verify that the values are not equal to numbers, texts and dates +assertThat(table).row().value().isNotEqualTo("5") + .value().isNotEqualTo("McGuiness") + .value().isNotEqualTo("Paul") + .value("birthdate").isNotEqualTo("1951-06-17"); +---- + +=== With UUID + +[source,java] +---- +// Verify that the values are not equal to UUID +assertThat(table).column() + .value().isNotEqualTo(UUID.fromString("30B443AE-C0C9-4790-9BEC-CE1380808435")) + .value().isNotEqualTo(UUID.fromString("0E2A1269-EFF0-4233-B87B-B53E8B6F164D")) + .value().isNotEqualTo(UUID.fromString("2B0D1BDD-909E-4362-BA10-C930BA82718D")); +---- + +=== With Character + +[source,java] +---- +// Verify that the values are not equal to Character +assertThat(table).column() + .value().isNotEqualTo('T') + .value().isNotEqualTo('e') + .value().isNotEqualTo('s') + .value().isNotEqualTo('t'); +---- + +== On the nullity of a value + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueNullity.html[AssertOnValueNullity] interface. + +These assertions allow to verify if a value (the value of a table, of a request or of a change) is null or not. + +[source,java] +---- +// Verify that the value at index 1 is null and the next value is not null +assertThat(table).column().value(1).isNull() + .value().isNotNull(); +// Verify the value is not null +assertThat(changes).change().rowAtStartPoint().value("live") + .isNotNull(); +---- + +== On the type of a value + +These assertions are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueType.html[AssertOnValueType] interface. + +This assertion allows to verify the type of a value (a value from a table, from a request or from changes). + +[source,java] +---- +// Verify that the value of the column called "firstname" +// of the fifth row of the table is a text +assertThat(table).row(4).value("firstname").isOfType(ValueType.TEXT); +// The same verification (with the specific method) +// on the third value of the second row of the request +assertThat(request).row(1).value(2).isText(); +// Verify that the value at start point of the first column +// of the first change is either a date or a number +assertThat(changes).change().column().valueAtStartPoint() + .isOfAnyOfTypes(ValueType.DATE, ValueType.NUMBER); +---- + +== On the class of a value + +This assertion is described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/assertions/AssertOnValueClass.html[AssertOnValueClass] interface. + +This assertion allows to verify the class of a value (a value from a table, from a request or from changes). + +[source,java] +---- +// Verify that the value of the column called "firstname" +// of the fifth row of the table is a String +assertThat(table).row(4).value("firstname").isOfClass(String.class); +// Verify that the value at start point of the first column +// of the first change is a Locale +assertThat(changes).change().column().valueAtStartPoint() + .isOfClass(Locale.class); +---- diff --git a/src/main/docs/modules/ROOT/pages/features/index.adoc b/src/main/docs/modules/ROOT/pages/features/index.adoc new file mode 100644 index 00000000..875d8474 --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/features/index.adoc @@ -0,0 +1,5 @@ += Features + +Before reading this page, it is recommended to be familiar with the xref:concepts/index.adoc[concepts of AssertJ-DB]. + +The purpose of this page is to show the different features of AssertJ-DB. diff --git a/src/main/docs/modules/ROOT/pages/features/navigation.adoc b/src/main/docs/modules/ROOT/pages/features/navigation.adoc new file mode 100644 index 00000000..d8869f90 --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/features/navigation.adoc @@ -0,0 +1,885 @@ += Navigation + +== With a Table or a Request as root + +As shown in the xref:concepts/navigation.adoc#tableorrequestasroot[concepts] (to easily understand this chapter it is important to know the concepts of assertj-db), +the `assertThat(...)` static method is used +to begin an assertion +on a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Table.html[Table] +or on a https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/type/Request.html[Request]. + +The navigation from a table or from a request are similar, so in most of the examples below a table will be used : + +[source,java] +---- +assertThat(tableOrRequest)... +---- + +If there is a difference if will be specified. + +All the navigation methods work from an origin point. +That means that if the method is executed from another point, +it is like the execution is from the point of view of the origin. + +There are some recurring points in the different navigation methods : + +* a method without parameter which allows to navigate on the next element after the element reached on the last call +(if it is the first call, navigate to the first element) +* a method with an `int` parameter (an index) which allows to navigate on the element which is +at the corresponding index +* a method with an `String` parameter (a column name) which allows to navigate on the element corresponding +at the column name + +=== To a Row + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToRow.html[ToRow] interface. + +The `row()` method allows to navigate to the next row after the row reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first row +assertThat(tableOrRequest).row()... +// It is possible to chain the calls to navigate to the next row +// after the first row (so the second row) +assertThat(tableOrRequest).row().row()... +---- + +The `row(int index)` method with `index` as parameter +allows to navigate to the row corresponding to row at the index. + +[source,java] +---- +// Navigate to the row at index 2 +assertThat(tableOrRequest).row(2)... +// It is possible to chain the calls to navigate to another row. +// Here row at index 6 +assertThat(tableOrRequest).row(2).row(6)... +// It is possible to combine the calls to navigate to the next row +// after the row at index 2. Here row at index 3 +assertThat(tableOrRequest).row(2).row()... +---- + +This picture shows from where it is possible to navigate to a row. + +[ditaa, target="db-navigation-with-table-or-request-to-row", shadows=false, transparent=true] +.... + +-----------+<--------+----------------------+ + +--------->|On a Column| |On a Value Of a Column| + | +-----+-----+-------->+---------------------++ + | | : | ++----------------+------+<--------+ | | +|On a Table Or a Request| navigate to a row | ++----+-----------+------+<--------+ | | + : | | v | + | | +-----+-----+<--------+-------------------+ | + | +--------->| On a Row | |On a Value Of a Row| | + | +--+----+---+-------->+----------+--------+ | + | ^ ^ : ^ : | + | navigate to a row | | | | | | + +----------------------+ +----+ +--------------------+----------+ + navigate to a row navigate to a row +.... + +The origin point of the `row(...)` methods is the Table or the Request. +So if the method is executed from a row, from a column or from a value +it is like if the method was executed from the Table or the Request. + +When the position is on a row, it is possible to return to the origin. + +[source,java] +---- +// Return to the table from a row of a table +assertThat(table).row().returnToTable()... +// Return to the request from a row of a request +assertThat(request).row().returnToRequest()... +---- + +That also means that the two navigations below are equivalent. + +[source,java] +---- +// Navigate to the first row +// Return to the table from this row +// Navigate to the next row +assertThat(table).row().returnToTable().row()... +// The same thing is done but the return to the table is implicit +assertThat(table).row().row()... +---- + +=== To a Column + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToColumn.html[ToColumn] interface. + +The `column()` method allows to navigate to the next column after the column reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first column +assertThat(tableOrRequest).column()... +// It is possible to chain the calls to navigate to the next column +// after the first column (so the second column) +assertThat(tableOrRequest).column().column()... +---- + +The `column(int index)` method with `index` as parameter +allows to navigate to the column corresponding to column at the index. + +[source,java] +---- +// Navigate to the column at index 2 +assertThat(tableOrRequest).column(2)... +// It is possible to chain the calls to navigate to another column. +// Here column at index 6 +assertThat(tableOrRequest).column(2).column(6)... +// It is possible to combine the calls to navigate to the next column +// after the column at index 2. Here column at index 3 +assertThat(tableOrRequest).column(2).column()... +// It is possible to combine the calls with other navigation methods +// Here first column +assertThat(tableOrRequest).row(2).column()... +// Here column at index 3 +assertThat(tableOrRequest).row(2).column(3)... +// Here column at index 4 because the origin remember last navigation to a column +assertThat(tableOrRequest).column(3).row(2).column()... +---- + +The `column(String columnName)` method with `columnName` as parameter +allows to navigate to the column corresponding to the column with the column name. + +[source,java] +---- +// Navigate to the column with the name "SURNAME" +assertThat(tableOrRequest).column("surname")... +// Like for the other methods, it is possible to chain the calls +assertThat(tableOrRequest).column("surname").column().column(6).column("id")... +---- + +This picture shows from where it is possible to navigate to a column. + +[ditaa, target="db-navigation-with-table-or-request-to-column", shadows=false, transparent=true] +.... + navigate to a column navigate to a column navigate to a column + +----------------------+ +----+ +---------------------+-----------+ + | | | | | | | + | v v : v | | + | +--+----+---+<--------+-----------+----------+| + | +--------->|On a Column| |On a Value Of a Column|| + | | +-----+-----+-------->+---------------------++| + : | | ^ | ++----+-----------+------+<--------+ | | +|On a Table Or a Request| navigate to a column | ++----------------+------+<--------+ | | + | | : | + | +-----+-----+<--------+-------------------+ | + +--------->| On a Row | |On a Value Of a Row+-=-+ + +-----------+-------->+-------------------+ +.... + +The origin point of the `column(...)` methods is the Table or the Request. +So if the method is executed from a row, from a column or from a value +it is like if the method was executed from the Table or The Request. + +When the position is on a column, it is possible to return to the origin. + +[source,java] +---- +// Return to the table from a column of a table +assertThat(table).column().returnToTable()... +// Return to the request from a column of a request +assertThat(request).column().returnToRequest()... +---- + +That also means that the two navigations below are equivalent. + +[source,java] +---- +// Navigate to the first column +// Return to the table from this column +// Navigate to the next column +assertThat(table).column().returnToTable().column()... +// The same thing is done but the return to the table is implicit +assertThat(table).column().column()... +---- + +=== To a Value + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToValue.html[ToValue] +and the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToValueFromRow.html[ToValueFromRow] interfaces. + +The `value()` method allows to navigate to the next value after the value reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first value +assertThat(tableOrRequest).row().value()... +// It is possible to chain the calls to navigate to the next value +// after the first value (so the second value) +assertThat(tableOrRequest).column().value().value()... +---- + +The `value(int index)` method with `index` as parameter +allows to navigate to the value corresponding to value at the index. + +[source,java] +---- +// Navigate to the value at index 2 +assertThat(tableOrRequest).column().value(2)... +// It is possible to chain the calls to navigate to another value. +// Here value at index 6 +assertThat(tableOrRequest).row(4).value(2).value(6)... +// It is possible to combine the calls to navigate to the next value +// after the value at index 2. Here value at index 3 +assertThat(tableOrRequest).column(4).value(2).value()... +// Here value at index 4 because the origin remember last navigation to a column +assertThat(tableOrRequest).column().value(3).row(2).column(0).value()... +---- + +The `value(String columnName)` method with `columnName` as parameter (only available from a row) +allows to navigate to the value of the column corresponding to the column with the column name. + +[source,java] +---- +// Navigate to the value of the column with the name "SURNAME" +assertThat(tableOrRequest).row().value("surname")... +// Like for the other methods, it is possible to chain the calls +assertThat(tableOrRequest).row().value("surname").value().value(6).value("id")... +---- + +This picture shows from where it is possible to navigate to a value. + +[ditaa, target="db-navigation-with-table-or-request-to-value", shadows=false, transparent=true] +.... + +--------------------+ + |navigate to a value | + : v + +-----+-----+<--+----------+-----------+=--+ + +-->|On a Column| |On a Value Of a Column| |navigate to a value + | +-----+-----+-->+----------------------+<--+ + | | ++----------------+------+<-+ +|On a Table Or a Request| ++----------------+------+<-+ + | | + | +-----+-----+<--+-------------------+=--+ + +-->| On a Row | |On a Value Of a Row| |navigate to a value + +-----+-----+-->+----------+--------+<--+ + : ^ + |navigate to a value | + +--------------------+ +.... + +The origin point of the `value(...)` methods is the Row or the Column. +So if the method is executed from a value +it is like if the method was executed from the Row or The Column. + +When the position is on a value, it is possible to return to the origin. + +[source,java] +---- +// Return to the column from a value +assertThat(table).column().value().returnToColumn()... +// Return to the row from a value +assertThat(request).row().value().returnToRow()... +---- + +That also means that the two navigations below are equivalent. + +[source,java] +---- +// Navigate to the first column +// Navigate to the first value +// Return to the column from this value +// Navigate to the next value +assertThat(table).column().value().returnToColumn().value()... +// The same thing is done but the return to the column is implicit +assertThat(table).column().value().value()... +---- + +== With Changes as root + +=== To Changes + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToChanges.html[ToChanges] interface. + +The `ofCreation()` method allows to navigate to the changes of creation. + +[source,java] +---- +// Navigate to the changes of creation +assertThat(changes).ofCreation()... +---- + +The `ofCreationOnTable()` method with `tableName` as parameter +allows to navigate to the changes of creation of a table. + +[source,java] +---- +// Navigate to the changes of creation on the "members" table +assertThat(changes).ofCreationOnTable("members")... +---- + +The `ofCreation()` method allows to navigate to the changes of modification. + +[source,java] +---- +// Navigate to the changes of modification +assertThat(changes).ofModification()... +---- + +The `ofModificationOnTable()` method with `tableName` as parameter +allows to navigate to the changes of modification of a table. + +[source,java] +---- +// Navigate to the changes of modification on the "members" table +assertThat(changes).ofModificationOnTable("members")... +---- + +The `ofCreation()` method allows to navigate to the changes of deletion. + +[source,java] +---- +// Navigate to the changes of deletion +assertThat(changes).ofDeletion()... +---- + +The `ofDeletionOnTable()` method with `tableName` as parameter +allows to navigate to the changes of deletion of a table. + +[source,java] +---- +// Navigate to the changes of deletion on the "members" table +assertThat(changes).ofDeletionOnTable("members")... +---- + +The `onTable(String tableName)` method with `tableName` as parameter +allows to navigate to the changes of a table. + +[source,java] +---- +// Navigate to all the changes on the "members" table +assertThat(changes).onTable("members")... +---- + +The `ofAll()` method allows to navigate to all the changes. + +[source,java] +---- +// Navigate to all the changes +assertThat(changes).ofAll()... +// The navigation can be chained +assertThat(changes).ofCreation().ofAll()... +---- + +This picture shows from where it is possible to navigate to changes. + +[ditaa, target="db-navigation-with-changes-to-changes", shadows=false, transparent=true] +.... + +--------------------------------+----------------------+ + | navigate to changes | : + | +-----+-----+<---+-----------+----------+ + |navigate to changes +-->|On a Column| |On a Value Of a Column| + +------------------+ | +-----+-----+--->+----------------------+ + | | | | + navigate to changes v : | | + +------------=+-----+-----+<-----+-----+---+-+<------+ + | |On Changes | |On a Change| + +------------>+-----+-----+----->+---------+-+<------+ + ^ | | + | | +-----+--+<---+-------------------+ + | +-->|On a Row| |On a Value Of a Row| + | +-----+--+--->+-----------+-------+ + | navigate to changes : | + +--------------------------------+-------------------+ +.... + +The origin point of these methods is the Changes. +So if the method is executed from a change, a column, a row or a value +it is like if the method was executed from the Changes. + +=== To a Change + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToChange.html[ToChange] interface. + +The `change()` method allows to navigate to the next change after the change reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first change +assertThat(changes).change()... +// It is possible to chain the calls to navigate to the next change +// after the first change (so the second change) +assertThat(changes).change().change()... +---- + +The `change(int index)` method with `index` as parameter +allows to navigate to the change corresponding to change at the index. + +[source,java] +---- +// Navigate to the change at index 2 +assertThat(changes).change().change(2)... +// It is possible to chain the calls to navigate to another change. +// Here change at index 7 +assertThat(changes).change(6).change()... +---- + +The `changeOnTable(String tableName)` method with `tableName` as parameter +allows to navigate to the next change corresponding to the table name after the change corresponding to the table name reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first change on "members" table +assertThat(changes).changeOnTable("members")... +// It is possible to chain the calls to navigate to the next change on the "members" table +// after the first change on the "members" table (so the second change) +assertThat(changes).changeOnTable("members").changeOnTable("members")... +---- + +The `changeOnTable(String tableName, int index)` method with `tableName` and `index` as parameters +allows to navigate to the change corresponding to change on the table name at the index. + +[source,java] +---- +// Navigate to the change at index 2 of "members" table +assertThat(changes).changeOnTable("members").changeOnTable("members", 2)... +// It is possible to chain the calls to navigate to another change. +// Here change at index 7 of "members" table +assertThat(changes).changeOnTable("members", 6).changeOnTable("members")... +---- + +There are 12 other methods which are derived from the 4 methods above : + +* `changeOfCreation()`, `changeOfModification()` and `changeOfDeletion()` +methods which allows to navigate to the next change of creation, modification and deletion like `change()` method + +[source,java] +---- +// If it is the first call, navigate to the first change of creation +assertThat(changes).changeOfCreation()... +// Navigate to the first change of creation +// and after the second change of creation +assertThat(changes).changeOfCreation().changeOfCreation()... +---- + +* `changeOfCreation(int index)`, `changeOfModification(int index)` and `changeOfDeletion(int index)` +methods with `index` as parameter which allows to navigate to the change of creation, modification and deletion corresponding to change of creation, modification and deletion at the index like `change(int index)` method + +[source,java] +---- +// Navigate to the change of modification at index 2 +assertThat(changes).changeOfModification() + .changeOfModification(2)... +// It is possible to chain the calls +// to navigate to another change of modification. +// Here change of modification at index 5 +assertThat(changes).changeOfModification(4) + .changeOfModification()... +---- + +* `changeOfCreationOnTable(String tableName)`, `changeOfModificationOnTable(String tableName)` and `changeOfDeletionOnTable(String tableName)` +methods with `tableName` as parameter which allows to navigate to the next change of creation, modification and deletion corresponding to the table name like `changeOnTable(String tableName)` method + +[source,java] +---- +// If it is the first call, navigate +// to the first change of creation on "members" table +assertThat(changes).changeOfCreationOnTable("members")... +// It is possible to chain the calls to navigate +// to the next change of creation on the "members" table +// after the first change of creation on the "members" table +// (so the second change of creation) +assertThat(changes).changeOfCreationOnTable("members") + .changeOfCreationOnTable("members")... +---- + +* `changeOfCreationOnTable(String tableName, int index)`, `changeOfModificationOnTable(String tableName, int index)` and `changeOfDeletionOnTable(String tableName, int index)` +methods with `tableName` and `index` as parameters which allows to navigate to the next change of creation, modification and deletion corresponding to the table name and index like `changeOnTable(String tableName, int index)` method + +[source,java] +---- +// Navigate to the change of deletion at index 2 of "members" table +assertThat(changes).changeOfDeletionOnTable("members") + .changeOfDeletionOnTable("members", 2)... +// It is possible to chain the calls +// to navigate to another change of deletion. +// Here change of deletion at index 7 of "members" table +assertThat(changes).changeOfDeletionOnTable("members", 6) + .changeOfDeletionOnTable("members")... +---- + +The `changeOnTableWithPks(String tableName, Object... pksValues)` method +allows to navigate to the change corresponding to the table and the primary keys. + +[source,java] +---- +// Navigate to the change with primary key 1 of "members" table +assertThat(changes).changeOnTableWithPks("members", 1)... +// It is possible to chain the calls to navigate to the next change +// after the change with primary key 1 of "members" table +assertThat(changes).changeOnTableWithPks("members", 1).change()... +---- + +This picture shows from where it is possible to navigate to a change. + +[ditaa, target="db-navigation-with-changes-to-change", shadows=false, transparent=true] +.... + navigate to change + +-------------+----------------------+ + | | : + navigate to change | +-----+-----+<---+-----------+----------+ + +------------------+ +-->|On a Column| |On a Value Of a Column| + | | | +-----+-----+--->+----------------------+ + : v | | ++-----+-----+<-----+-----+---+-+<------+ +|On Changes | |On a Change| ++-----------+----->+-----+---+-+<------+ + | ^ | | + | | | +-----+--+<---+-------------------+ + navigate to change| | +-->|On a Row| |On a Value Of a Row| + | | +-----+--+--->+-----------+-------+ + | | : | + +-----+-------------+-------------------+ + navigate to change +.... + +The origin point of the `change(...)` methods is the current Changes +and the origin point of other methods is the Changes of origin. +So if the method is executed from a change, a column, a row or a value +it is like if the method was executed from these origins. + +That means there is an important difference. + +[source,java] +---- +// Navigate to the changes of deletion +// Navigate to the first change of this changes of deletion +assertThat(changes).ofDeletion().change()... +// Navigate to the changes of deletion +// Navigate to the first change of this changes of creation +assertThat(changes).ofDeletion().changeOfCreation()... +// This is equivalent to +assertThat(changes).ofDeletion().ofAll().changeOfCreation()... +---- + +When the position is on a change, it is possible to return to the origin. + +[source,java] +---- +// Return to the change from a column +assertThat(changes).change().returnToChanges()... +---- + +That also means that the two navigations below are equivalent. + +[source,java] +---- +// Navigate to the first change +// Return to the changes +// Navigate to the next change +assertThat(changes).change().returnToChanges().change()... +// The same thing is done but the return to the changes is implicit +assertThat(changes).change().change()... +---- + +=== To a Row + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToRowFromChange.html[ToRowFromChange] interface. + +The `rowAtStartPoint()` and `rowAtEndPoint()` methods +allows to navigate to the row at the start point and at the end point. + +[source,java] +---- +// Navigate to the row at the start point +assertThat(changes).change().rowAtStartPoint()... +// Navigate to the row at the end point (note that the methods can be chained) +assertThat(changes).change().rowAtStartPoint().rowAtEndPoint()... +---- + +This picture shows from where it is possible to navigate to a row. + +[ditaa, target="db-navigation-with-changes-to-row", shadows=false, transparent=true] +.... + +-----------+<---+----------------------+ + +-->|On a Column| |On a Value Of a Column| + | +-----+--+--+--->+--------------------+-+ + | | : : ++-----------+<-----+-----+-----+<--+ | | +|On Changes | |On a Change| navigate to a row | ++-----------+----->+-+---+-----+<--+ | | + : | | v | + navigate to a row| | +-----+--+<---+-------------------+ | + | +-->|On a Row| |On a Value Of a Row| | + +------>++--+--+-+--->+-----------+-------+ | + : ^ ^ | | + | | | | | + +--+ +------------------+-----------+ + navigate to a row navigate to a row +.... + +The origin point of the `rowAtStartPoint()` and `rowAtEndPoint()` methods is the Change. +So if the method is executed from a row, from a column or from a value +it is like if the method was executed from the Change. + +When the position is on a row, it is possible to return to the origin. + +[source,java] +---- +// Return to the change from a row +assertThat(changes).change().rowAtStartPoint().returnToChange()... +---- + +That also means that the two navigations below are equivalent. + +[source,java] +---- +// Navigate to the first change +// Navigate to the row at start point +// Return to the change from this column +// Navigate to the row at end point +assertThat(changes).change().rowAtStartPoint().returnToChange().rowAtEndPoint()... +// The same thing is done but the return to the change is implicit +assertThat(changes).change().rowAtStartPoint().rowAtEndPoint()... +---- + +=== To a Column + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToColumn.html[ToColumn] +and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToColumnFromChange.html[ToColumnFromChange] interfaces. + +The `column()` method allows to navigate to the next column after the column reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first column +assertThat(changes).change().column()... +// It is possible to chain the calls to navigate to the next column +// after the first column (so the second column) +assertThat(changes).change().column().column()... +---- + +The `column(int index)` method with `index` as parameter +allows to navigate to the column corresponding to column at the index. + +[source,java] +---- +// Navigate to the column at index 2 +assertThat(changes).change().column(2)... +// It is possible to chain the calls to navigate to another column. +// Here column at index 6 +assertThat(changes).change().column(2).column(6)... +// It is possible to combine the calls to navigate to the next column +// after the column at index 2. Here column at index 3 +assertThat(changes).change().column(2).column()... +// It is possible to combine the calls with other navigation methods +// Here first column +assertThat(changes).change().rowAtStartPoint().column()... +// Here column at index 3 +assertThat(changes).change().rowAtEndPoint().column(3)... +// Here column at index 4 because the origin remember last navigation to a column +assertThat(changes).change().column(3).rowAtEndPoint().column()... +---- + +The `column(String columnName)` method with `columnName` as parameter +allows to navigate to the column corresponding to the column with the column name. + +[source,java] +---- +// Navigate to the column with the name "SURNAME" +assertThat(changes).change().column("surname")... +// Like for the other methods, it is possible to chain the calls +assertThat(changes).change().column("surname").column().column(6).column("id")... +---- + +The `columnAmongTheModifiedOnes()` method allows to navigate to the next column with modifications after the column reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first column with modifications +assertThat(changes).change().columnAmongTheModifiedOnes()... +// It is possible to chain the calls to navigate to the next column +// after the first column (so the second column with modifications) +assertThat(changes).change().columnAmongTheModifiedOnes() + .columnAmongTheModifiedOnes()... +---- + +The `columnAmongTheModifiedOnes(int index)` method with `index` as parameter allows to navigate to the column with modifications corresponding to column at the index. + +[source,java] +---- +// Navigate to the column at index 2 (the third column with modifications) +assertThat(changes).change().columnAmongTheModifiedOnes(2)... +// It is possible to chain the calls to navigate to another column. +// Here column at index 0 (the first column with modifications) +assertThat(changes).change().columnAmongTheModifiedOnes(2) + .columnAmongTheModifiedOnes(0)... +---- + +The `columnAmongTheModifiedOnes(String columnName)` method with `columnName` as parameter +allows to navigate to the column with modifications corresponding to the column with the column name. + +[source,java] +---- +// Navigate to the column with modifications and the name "SURNAME" +assertThat(changes).change().columnAmongTheModifiedOnes("surname")... +// Like for the other methods, it is possible to chain the calls +assertThat(changes).change().column("surname").columnAmongTheModifiedOnes() + .column(6).columnAmongTheModifiedOnes("id")... +---- + +This picture shows from where it is possible to navigate to a column. + +[ditaa, target="db-navigation-with-changes-to-column", shadows=false, transparent=true] +.... + navigate to a column navigate to a column + +---+ +-----------------+-----------+ + | | | | | + : v v | | + +------>+-+---+-----+<---+-----------+----------+| + navigate to a column| +-->|On a Column| |On a Value Of a Column|| + | | +-----+-----+--->+----------------------+| + : | | ^ | ++-----------+<-----+-+---+-----+<--+ | | +|On Changes | |On a Change| navigate to a column | ++-----------+----->+-----+-----+<--+ | | + | | : | + | +-----+--+<---+-------------------+ | + +-->|On a Row| |On a Value Of a Row|=-----+ + +--------+--->+-------------------+ +.... + +The origin point of the `column(...)` methods is the Change. +So if the method is executed from a row, from a column or from a value +it is like if the method was executed from the Change. + +When the position is on a column, it is possible to return to the origin. + +[source,java] +---- +// Return to the change from a column +assertThat(changes).change().column().returnToChange()... +---- + +That also means that the two navigations below are equivalent. + +[source,java] +---- +// Navigate to the first change +// Navigate to the first column +// Return to the change from this column +// Navigate to the next column +assertThat(changes).change().column().returnToChange().column()... +// The same thing is done but the return to the change is implicit +assertThat(changes).change().column().column()... +---- + +=== To a Value + +These methods are described in the https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToValue.html[ToValue], +https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToValueFromColumn.html[ToValueFromColumn] +and https://www.javadoc.io/doc/org.assertj/assertj-db/latest/org/assertj/db/api/navigation/ToValueFromRow.html[ToValueFromRow] interfaces. + +This picture shows from where it is possible to navigate to a value. + +The `value()` method (only available from a row) allows to navigate to the next value after the value reached on the last call. + +[source,java] +---- +// If it is the first call, navigate to the first value +assertThat(changes).change().rowAtEndPoint().value()... +// It is possible to chain the calls to navigate to the next value +// after the first value (so the second value) +assertThat(changes).change().rowAtEndPoint().value().value()... +---- + +The `value(int index)` method with `index` as parameter (only available from a row) +allows to navigate to the value corresponding to value at the index. + +[source,java] +---- +// Navigate to the value at index 2 +assertThat(changes).change().rowAtEndPoint().value(2)... +// It is possible to chain the calls to navigate to another value. +// Here value at index 6 +assertThat(changes).change().rowAtEndPoint().value(2).value(6)... +// It is possible to combine the calls to navigate to the next value +// after the value at index 2. Here value at index 3 +assertThat(changes).change().rowAtEndPoint().value(2).value()... +// Here value at index 4 because the origin remember last navigation to the row +assertThat(changes).change().rowAtEndPoint().value(3).column(2).rowAtEndPoint().value()... +---- + +The `value(String columnName)` method with `columnName` as parameter (only available from a row) +allows to navigate to the value of the column corresponding to the column with the column name. + +[source,java] +---- +// Navigate to the value of the column with the name "SURNAME" +assertThat(changes).change().rowAtEndPoint().value("surname")... +// Like for the other methods, it is possible to chain the calls +assertThat(changes).change().rowAtEndPoint().value("surname").value().value(6).value("id")... +---- + +The `valueAtStartPoint()` and `valueAtEndPoint()` methods (only available from a column) +allows to navigate to the value at the start point and at the end point. + +[source,java] +---- +// Navigate to the value at the start point of the row +assertThat(changes).change().column().valueAtStartPoint()... +// Navigate to the value at the end point of the row (note that the methods can be chained) +assertThat(changes).change().column().valueAtStartPoint().valueAtEndPoint()... +---- + +This picture shows from where it is possible to navigate to a value. + +[ditaa, target="db-navigation-with-changes-to-value", shadows=false, transparent=true] +.... + +-------------------+ + |navigate to a value| + : v + +---+-------+<---+------+---------------+=-+ + +-->|On a Column| |On a Value Of a Column| |navigate to a value + | +-----+-----+--->+----------------------+<-+ + | | ++-----------+<-+-----+-----+<--+ +|On Changes | |On a Change| ++-----------+->+-----+-----+<--+ + | | + | +-----+--+<---+-------------------+=-+ + +-->|On a Row| |On a Value Of a Row| |navigate to a value + +---+----+--->+---------+---------+<-+ + : ^ + |navigate to a value| + +-------------------+ +.... + +The origin point of the `value(...)` methods is the Row or the Column. +So if the method is executed from a value +it is like if the method was executed from the Row or The Column. + +When the position is on a value, it is possible to return to the origin. + +[source,java] +---- +// Return to the column from a value +assertThat(changes).change().column().valueAtEndPoint().returnToColumn()... +// Return to the row from a value +assertThat(changes).change().rowAtEndPoint().value().returnToRow()... +---- + +That also means that the two navigations below are equivalent. + +[source,java] +---- +// Navigate to the first change +// Navigate to the row at end point +// Navigate to the first value +// Return to the column from this value +// Navigate to the next value +assertThat(changes).change().rowAtEndPoint().value().returnToRow().value()... +// The same thing is done but the return to the row is implicit +assertThat(changes).change().rowAtEndPoint().value().value()... +---- diff --git a/src/main/docs/modules/ROOT/pages/index.adoc b/src/main/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..f17476dd --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,15 @@ +:navtitle: Overview += AssertJ DB + +image::assertj-db_icon.png[] + +AssertJ-DB provides assertions to test data in a database. +It requires Java 8 or later and can be used with either JUnit or TestNG. + +If you need additional assertions, please create a ticket in the https://github.com/assertj/assertj-db/issues?labels=&milestone=&page=1&state=open[AssertJ-DB issue tracker]. + +AssertJ-DB is hosted on GitHub: https://github.com/assertj/assertj-db[https://github.com/assertj/assertj-db]. + +Big thanks to Joel Costigliola for his welcome, for his help and for having accepted to associate this project with a great project like AssertJ. + +_Régis Pouiller (AssertJ-DB creator)_ diff --git a/src/main/docs/modules/ROOT/pages/quickstart.adoc b/src/main/docs/modules/ROOT/pages/quickstart.adoc new file mode 100644 index 00000000..11277e39 --- /dev/null +++ b/src/main/docs/modules/ROOT/pages/quickstart.adoc @@ -0,0 +1,71 @@ += Quick start + +Suppose that the database contains this table *MEMBERS* : + +|=== +|ID |NAME |FIRSTNAME |SURNAME |BIRTHDATE |SIZE + +|1 |'Hewson' |'Paul David' |'Bono' |05-10-60 |1.75 +|2 |'Evans' |'David Howell' |'The Edge' |08-08-61 |1.77 +|3 |'Clayton' |'Adam' |  |03-13-60 |1.78 +|4 |'Mullen' |'Larry' |  |10-31-61 |1.70 +|=== + +To quickly start using DataBase assertions, follow the steps below. + +== Add the assertj-db dependency to your project + +=== Maven + +[source,xml,subs=attributes+] +---- + + org.assertj + assertj-db + {page-component-version} + test + +---- + +=== Gradle + +For Gradle users (using the Maven Central Repository) + +[source,java,subs=attributes+] +---- +testCompile("org.assertj:assertj-db:{page-component-version}") +---- + +=== Other dependency management tool + +Check this page to find the relevant http://search.maven.org/#artifactdetails|org.assertj|assertj-db|{page-component-version}|bundle[assertj db dependency declaration]. + +== Statically import org.assertj.db.api.Assertions.assertThat + +\... and use your preferred IDE code completion after assertThat. + +Example from {assertj-examples-repo}/blob/main/assertions-examples/src/test/java/org/assertj/examples/db/TableAssertionExamples.java[TableAssertionExamples.java] : + +[source,java] +---- +include::example$TableAssertionExamples.java[tags=user_guide] +---- + +In this simple example you can see many xref:concepts/index.adoc[concepts of AssertJ-DB] (the concepts are simple, but I advise you to take the time to get to know them well) : + +* xref::concepts/elements.adoc[The elements] : +** xref::concepts/elements.adoc#table[Table] which represents a table in the database +** xref::concepts/elements.adoc#column[Column] which represents a column of the table +** xref::concepts/elements.adoc#row[Row] which represents a row of the table +** xref::concepts/elements.adoc#value[Value] which represents a value in a column or in a row +* xref::concepts/navigation.adoc#tableorrequestasroot[The navigation] : +** The first check, navigates from the table to the column called "name" +(``column("name")`` moves the assertion to the column), +from this column to the first value (the first call of ``value()`` moves to the first value) +and after that to each value (each call of ``value()`` moves to the next value of the column). +** The second check, navigates from the table to the row with index 1 +(``row(1)`` moves the assertion to the row), +from this row to the first value +and after that to each value (``value()`` calls have similar behavior for rows and columns). +* xref::concepts/datetime.adoc[DateValue] : The preferred way to compare values with date, time and date/time is to use java.time.LocalDate, java.time.LocalTime, java.time.LocalDateTime. +But for the backward compatibility, it's always possible to use AssertJ-DB DateValue utilities. diff --git a/src/test/java/org/example/db/TableAssertionExamples.java b/src/test/java/org/example/db/TableAssertionExamples.java new file mode 100644 index 00000000..cfe777a5 --- /dev/null +++ b/src/test/java/org/example/db/TableAssertionExamples.java @@ -0,0 +1,45 @@ +package org.example.db; + +// tag::user_guide[] +import static org.assertj.db.api.Assertions.assertThat; + +import org.assertj.db.type.AssertDbConnection; +import org.assertj.db.type.AssertDbConnectionFactory; +import org.assertj.db.type.DateValue; +import org.assertj.db.type.Table; + +// end::user_guide[] + +import org.junit.Test; + +public class TableAssertionExamples { +// tag::user_guide[] + private final AssertDbConnection assertDbConnection = AssertDbConnectionFactory.of("jdbc:h2:mem:test", "sa", "").create(); + +// end::user_guide[] + /** + * This example shows a simple case of test. + */ + @Test + public void basic_table_assertion_examples() { +// tag::user_guide[] + Table table = assertDbConnection.table("members").build(); + + // Check column "name" values + assertThat(table).column("name") + .value().isEqualTo("Hewson") + .value().isEqualTo("Evans") + .value().isEqualTo("Clayton") + .value().isEqualTo("Mullen"); + + // Check row at index 1 (the second row) values + assertThat(table).row(1) + .value().isEqualTo(2) + .value().isEqualTo("Evans") + .value().isEqualTo("David Howell") + .value().isEqualTo("The Edge") + .value().isEqualTo(DateValue.of(1961, 8, 8)) + .value().isEqualTo(1.77); +// end::user_guide[] + } +}