Introduce 3.0 Python driver docs and tests. Implement new fetch BDD s…

…teps in 3.0 drivers (#700) ## Usage and product changes We introduce updated documentation, usage examples, and automated tests for the Java driver, to cover all the existing driver's APIs by sustainable validations. Additionally, we implement additional BDD steps to check concept documents in BDDs for other 3.0 drivers: Rust and Python. As a small bonus, the protocol has been updated, and `Ok` `QueryAnswer`s receive correct `QueryType`s from the server instead of the client-side hardcode usage. ## Implementation For behaviour tests, the already existing architecture is preserved, and only the steps are rewritten to match the new definitions. For integration tests, the new approach of the Python driver is chosen, and all the excessive tests are removed. Now, we only write `example` tests and tests to cover language-specific values (especially our implementations and their interfaces). For docs, the old instruments are used without changes. For `README`, the `example` integration test parsing instrument is used as in Rust and Python.
typedb · Oct 23, 2024 · 48ff5e1 · 48ff5e1
1 parent a4e0087
commit 48ff5e1
Show file tree

Hide file tree

Showing 76 changed files with 4,056 additions and 2,444 deletions.
diff --git a/.factory/automation.yml b/.factory/automation.yml
@@ -74,8 +74,7 @@ build:
           sudo mv /var/tmp/doxygen /usr/local/bin/ && sudo chmod +x /usr/local/bin/doxygen
         bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
         # TODO: Temporarily update only 3.0 drivers
-        # DOCS_DIRS="docs/modules/ROOT/partials/rust docs/modules/ROOT/partials/java docs/modules/ROOT/partials/python docs/modules/ROOT/partials/nodejs docs/modules/ROOT/partials/cpp docs/modules/ROOT/partials/c docs/modules/ROOT/partials/csharp"
-        DOCS_DIRS=("docs/modules/ROOT/partials/rust" "docs/modules/ROOT/partials/python")
+        DOCS_DIRS=("docs/modules/ROOT/partials/rust" "docs/modules/ROOT/partials/java" "docs/modules/ROOT/partials/python")
         find "${DOCS_DIRS[@]}" -type f ! -name 'api-reference.adoc' -exec rm -f {} \;
         tool/docs/update.sh
         git add "${DOCS_DIRS[@]}"
@@ -169,21 +168,27 @@ build:
         tool/test/stop-core-server.sh
         exit $TEST_SUCCESS
 
-#    test-java-behaviour-core:
-#      image: vaticle-ubuntu-22.04
-#      dependencies:
-#        - build
-#      command: |
-#        export ARTIFACT_USERNAME=$REPO_TYPEDB_USERNAME
-#        export ARTIFACT_PASSWORD=$REPO_TYPEDB_PASSWORD
-#        bazel run @vaticle_dependencies//distribution/artifact:create-netrc
-#        bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
-#        .factory/test-core.sh //java/test/behaviour/connection/... --test_output=errors --jobs=1
-#        # TODO: delete --jobs=1 if we fix the issue with excess memory usage
-#        .factory/test-core.sh //java/test/behaviour/concept/... --test_output=errors
-#        .factory/test-core.sh //java/test/behaviour/driver/query/... --test_output=errors
-#        .factory/test-core.sh //java/test/behaviour/query/language/... --test_output=errors --jobs=1
-#
+#        source tool/test/start-cloud-servers.sh 3 && # use source to receive export vars
+#          .factory/test-cloud.sh //java/test/integration/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&
+#          export TEST_SUCCESS=0 || export TEST_SUCCESS=1
+#        tool/test/stop-cloud-servers.sh
+#        exit $TEST_SUCCESS
+
+    test-java-behaviour-core:
+      image: vaticle-ubuntu-22.04
+      dependencies:
+        - build
+      command: |
+        export ARTIFACT_USERNAME=$REPO_TYPEDB_USERNAME
+        export ARTIFACT_PASSWORD=$REPO_TYPEDB_PASSWORD
+        bazel run @vaticle_dependencies//distribution/artifact:create-netrc
+        bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
+        
+        tool/test/start-core-server.sh &&
+          .factory/test-core.sh //java/test/behaviour/... --test_output=errors --jobs=1 &&
+          export TEST_SUCCESS=0 || export TEST_SUCCESS=1
+        tool/test/stop-core-server.sh
+
 #    test-java-behaviour-cloud:
 #      image: vaticle-ubuntu-22.04
 #      dependencies:
@@ -193,11 +198,12 @@ build:
 #        export ARTIFACT_PASSWORD=$REPO_TYPEDB_PASSWORD
 #        bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
 #        bazel run @vaticle_dependencies//distribution/artifact:create-netrc
-#        .factory/test-cloud.sh //java/test/behaviour/connection/... --test_output=errors --jobs=1
-#        # TODO: delete --jobs=1 if we fix the issue with excess memory usage
-#        .factory/test-cloud.sh //java/test/behaviour/concept/... --test_output=errors
-#        .factory/test-cloud.sh //java/test/behaviour/driver/query/... --test_output=errors
-#        .factory/test-cloud.sh //java/test/behaviour/query/language/... --test_output=errors --jobs=1
+#
+#        source tool/test/start-cloud-servers.sh 3 && # use source to receive export vars
+#          .factory/test-cloud.sh //java/test/behaviour/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&
+#          export TEST_SUCCESS=0 || export TEST_SUCCESS=1
+#        tool/test/stop-cloud-servers.sh
+#        exit $TEST_SUCCESS
 
     test-python-integration:
       image: vaticle-ubuntu-22.04
@@ -253,7 +259,7 @@ build:
 #        bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
 #        bazel run @vaticle_dependencies//distribution/artifact:create-netrc
 #
-#        source tool/test/start-cloud-servers.sh && # use source to receive export vars
+#        source tool/test/start-cloud-servers.sh 3 && # use source to receive export vars
 #          .factory/test-cloud.sh //python/tests/behaviour/... --test_env=ROOT_CA=$ROOT_CA --test_output=streamed --jobs=1 &&
 #          export TEST_SUCCESS=0 || export TEST_SUCCESS=1
 #        tool/test/stop-cloud-servers.sh
@@ -312,7 +318,7 @@ build:
 #        export ARTIFACT_USERNAME=$REPO_TYPEDB_USERNAME
 #        export ARTIFACT_PASSWORD=$REPO_TYPEDB_PASSWORD
 #        bazel run @vaticle_dependencies//distribution/artifact:create-netrc
-#        source tool/test/start-cloud-servers.sh && # use source to receive export vars
+#        source tool/test/start-cloud-servers.sh 3 && # use source to receive export vars
 #          .factory/test-cloud.sh //nodejs/test/behaviour/connection/database/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&
 #          .factory/test-cloud.sh //nodejs/test/behaviour/connection/session/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&
 #          .factory/test-cloud.sh //nodejs/test/behaviour/connection/transaction/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&
@@ -381,7 +387,7 @@ build:
 #        export ARTIFACT_PASSWORD=$REPO_TYPEDB_PASSWORD
 #        bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
 #        bazel run @vaticle_dependencies//distribution/artifact:create-netrc
-#        source tool/test/start-cloud-servers.sh &&
+#        source tool/test/start-cloud-servers.sh 3 &&
 #          .factory/test-cloud.sh //cpp/test/behaviour/connection/database/... --test_env=ROOT_CA=$ROOT_CA --test_output=streamed --jobs=1 &&
 #          .factory/test-cloud.sh //cpp/test/behaviour/connection/session/... --test_env=ROOT_CA=$ROOT_CA --test_output=streamed --jobs=1 &&
 #          .factory/test-cloud.sh //cpp/test/behaviour/connection/transaction/... --test_env=ROOT_CA=$ROOT_CA --test_output=streamed --jobs=1 &&
@@ -452,7 +458,7 @@ build:
 #        export ARTIFACT_PASSWORD=$REPO_TYPEDB_PASSWORD
 #        bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
 #        bazel run @vaticle_dependencies//distribution/artifact:create-netrc
-#        source tool/test/start-cloud-servers.sh &&
+#        source tool/test/start-cloud-servers.sh 3 &&
 #          .factory/test-cloud.sh //csharp/Test/Behaviour/Connection/Database/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&
 #          .factory/test-cloud.sh //csharp/Test/Behaviour/Connection/Session/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&
 #          .factory/test-cloud.sh //csharp/Test/Behaviour/Connection/Transaction/... --test_env=ROOT_CA=$ROOT_CA --test_output=errors --jobs=1 &&

diff --git a/dependencies/vaticle/artifacts.bzl b/dependencies/vaticle/artifacts.bzl
@@ -25,7 +25,7 @@ def vaticle_typedb_artifact():
         artifact_name = "typedb-all-{platform}-{version}.{ext}",
         tag_source = deployment["artifact"]["release"]["download"],
         commit_source = deployment["artifact"]["snapshot"]["download"],
-        commit = "b52a7e6da7e59fd32aea1c56d583ecc73ae62412"
+        commit = "2c110dc1dce03270842b3a92f859f0b4a7a18cb4"
     )
 
 #def vaticle_typedb_cloud_artifact():

diff --git a/dependencies/vaticle/repositories.bzl b/dependencies/vaticle/repositories.bzl
@@ -28,12 +28,12 @@ def vaticle_typedb_protocol():
     git_repository(
         name = "vaticle_typedb_protocol",
         remote = "https://github.com/typedb/typedb-protocol",
-        tag = "3.0.0-alpha-6",  # sync-marker: do not remove this comment, this is used for sync-dependencies by @vaticle_typedb_protocol
+        commit = "56eb6ef6db0d0721800f46512e2ee5e02aad6adb",  # sync-marker: do not remove this comment, this is used for sync-dependencies by @vaticle_typedb_protocol
     )
 
 def vaticle_typedb_behaviour():
     git_repository(
         name = "vaticle_typedb_behaviour",
         remote = "https://github.com/typedb/typedb-behaviour",
-        commit = "52d3aca4b833865861550262edd760a9ca592be8",  # sync-marker: do not remove this comment, this is used for sync-dependencies by @vaticle_typedb_behaviour
+        commit = "4ec10ad5a5f9a7fd19b327240a33bcb77e502f57",  # sync-marker: do not remove this comment, this is used for sync-dependencies by @vaticle_typedb_behaviour
     )
diff --git a/docs/modules/ROOT/partials/java/answer/ConceptDocumentIterator.adoc b/docs/modules/ROOT/partials/java/answer/ConceptDocumentIterator.adoc
@@ -0,0 +1,75 @@
+[#_ConceptDocumentIterator]
+=== ConceptDocumentIterator
+
+*Package*: `com.typedb.driver.api.answer`
+
+*Superinterfaces:*
+
+* `java.util.Iterator<JSON>`
+* `QueryAnswer`
+
+Represents an iterator over concept documents (represented as ``JSON``s) returned as a server answer.
+
+// tag::methods[]
+[#_ConceptDocumentIterator_asConceptDocuments_]
+==== asConceptDocuments
+
+[source,java]
+----
+@CheckReturnValue
+default ConceptDocumentIterator asConceptDocuments()
+----
+
+Casts the query answer to ``ConceptDocumentIterator``. 
+
+
+[caption=""]
+.Returns
+`ConceptDocumentIterator`
+
+[caption=""]
+.Code examples
+[source,java]
+----
+concept.asConceptDocuments();
+----
+
+[#_ConceptDocumentIterator_isConceptDocuments_]
+==== isConceptDocuments
+
+[source,java]
+----
+default boolean isConceptDocuments()
+----
+
+Checks if the query answer is a ``ConceptDocumentIterator``. 
+
+
+[caption=""]
+.Returns
+`boolean`
+
+[caption=""]
+.Code examples
+[source,java]
+----
+concept.isConceptDocuments();
+----
+
+[#_ConceptDocumentIterator_stream_]
+==== stream
+
+[source,java]
+----
+@CheckReturnValue
+java.util.stream.Stream<JSON> stream()
+----
+
+
+
+[caption=""]
+.Returns
+`java.util.stream.Stream<JSON>`
+
+// end::methods[]
+
diff --git a/docs/modules/ROOT/partials/java/answer/ConceptRow.adoc b/docs/modules/ROOT/partials/java/answer/ConceptRow.adoc
@@ -15,7 +15,7 @@ Contains a row of concepts with a header.
 java.util.stream.Stream<java.lang.String> columnNames()
 ----
 
-Produces a stream over all column names (header) in this ``ConceptRow``. Shared between all the rows in a QueryAnswer. 
+Produces a stream over all column names (variables) in the header of this ``ConceptRow``. Shared between all the rows in a QueryAnswer. 
 
 
 [caption=""]
@@ -26,7 +26,7 @@ Produces a stream over all column names (header) in this ``ConceptRow``. Shared
 .Code examples
 [source,java]
 ----
-conceptRow.header();
+conceptRow.columnNames();
 ----
 
 [#_ConceptRow_concepts_]
@@ -38,7 +38,7 @@ conceptRow.header();
 java.util.stream.Stream<? extends Concept> concepts()
 ----
 
-Produces an iterator over all concepts in this `ConceptRow`, skipping empty results. 
+Produces a stream over all concepts in this `ConceptRow`, skipping empty results. 
 
 
 [caption=""]
@@ -61,7 +61,7 @@ conceptRow.concepts();
 Concept get(java.lang.String columnName)
 ----
 
-Retrieves a concept for a given variable name. 
+Retrieves a concept for a given column name (variable). 
 
 
 [caption=""]
@@ -70,7 +70,7 @@ Retrieves a concept for a given variable name.
 [options="header"]
 |===
 |Name |Description |Type
-a| `columnName` a| the column name (header) a| `java.lang.String`
+a| `columnName` a| the variable (column name from ``column_names``) a| `java.lang.String`
 |===
 
 [caption=""]
@@ -93,7 +93,7 @@ conceptRow.get(columnName);
 Concept getIndex(long columnIndex)
 ----
 
-Retrieves a concept for a given variable name. 
+Retrieves a concept for a given index of the header (``columnNames``). 
 
 
 [caption=""]
@@ -136,7 +136,7 @@ Retrieves the executed query's type of this ``ConceptRow``. Shared between all t
 .Code examples
 [source,java]
 ----
-conceptRow.queryType();
+conceptRow.getQueryType();
 ----
 
 // end::methods[]

diff --git a/docs/modules/ROOT/partials/java/answer/ConceptRowIterator.adoc b/docs/modules/ROOT/partials/java/answer/ConceptRowIterator.adoc
@@ -8,6 +8,8 @@
 * `java.util.Iterator<ConceptRow>`
 * `QueryAnswer`
 
+Represents an iterator over ``ConceptRow``s returned as a server answer.
+
 // tag::methods[]
 [#_ConceptRowIterator_asConceptRows_]
 ==== asConceptRows
@@ -18,13 +20,20 @@
 default ConceptRowIterator asConceptRows()
 ----
 
-Casts the query answer to ``ConceptRowStreamQueryAnswer``.
+Casts the query answer to ``ConceptRowIterator``. 
 
 
 [caption=""]
 .Returns
 `ConceptRowIterator`
 
+[caption=""]
+.Code examples
+[source,java]
+----
+concept.asConceptRows();
+----
+
 [#_ConceptRowIterator_isConceptRows_]
 ==== isConceptRows
 
@@ -33,13 +42,20 @@ Casts the query answer to ``ConceptRowStreamQueryAnswer``.
 default boolean isConceptRows()
 ----
 
-Checks if the query answer is a ``ConceptRowStream``.
+Checks if the query answer is a ``ConceptRowIterator``. 
 
 
 [caption=""]
 .Returns
 `boolean`
 
+[caption=""]
+.Code examples
+[source,java]
+----
+concept.isConceptRows();
+----
+
 [#_ConceptRowIterator_stream_]
 ==== stream
 
@@ -49,11 +65,19 @@ Checks if the query answer is a ``ConceptRowStream``.
 java.util.stream.Stream<ConceptRow> stream()
 ----
 
+Creates a stream over ``ConceptRow``s based on this iterator. 
 
 
 [caption=""]
 .Returns
 `java.util.stream.Stream<ConceptRow>`
 
+[caption=""]
+.Code examples
+[source,java]
+----
+answer.asConceptRows().stream();
+----
+
 // end::methods[]
 
diff --git a/docs/modules/ROOT/partials/java/answer/ConceptTree.adoc b/docs/modules/ROOT/partials/java/answer/ConceptTree.adoc