Couchbase Java SDK Documentation
This repository hosts the documentation source for the Couchbase Java SDK.
Contributing
Check out our contributing guide to learn how to:
-
submit a bug or feedback issue
-
set up your documentation workspace
-
build the documentation
-
submit a pull request
Thank you for helping to make the documentation better.
Docs Component Configuration
This repository contains an Antora docs component. Keep in mind these key repository features:
-
Component name, version, and start page are configured in each branch’s antora.yml file.
-
The navigation for all of the modules is stored in the ROOT module’s nav.adoc file.
-
Production branches use the release/X.Y naming pattern (e.g., release/2.7, release/3.0).
-
The docs site playbook instructs Antora to automatically aggregate any branch names that start with release/.
-
Documentation Site Toolchain
The documentation source files are marked up with AsciiDoc. Once merged into a version branch, the source files and their assets are aggregated, converted to HTML, and published by Antora to our staging and production sites. The docs components and site UI are orchestrated by the docs site playbook. See the contributing guide to learn more.
Documentation Code Sample Testing
To ensure that the code samples included in the documentation are correct and produce the results we expect, we have setup scripts that build and test each example file.
For testing we use the bats-core automation framework to run the code and bats-assert assertion library to make assertions on the output where necessary.
The tests run against the latest Couchbase Server docker image with the relevant SDK (Java in this case) provided alongside it.
To facilitate running the tests there is a Makefile
in the /modules
directory of the project.
There you will find all the relevant commands needed to execute the docker container and the test/build scripts.
Running a test
Before you can run the tests you will need to ensure you have Docker and npm available on your machine.
To run the example tests you will need to build the testing Docker image, run the container and execute your tests.
Tip
|
After your first build of the docker image you won’t need to build it every time you want to run the tests. |
Here are the steps required to achieve this:
-
From the root directory run
make cb-build
to build a local image of Couchbase Server + Java SDK. -
Once that has completed successfully you can run
make cb-start
to run the docker container.
Note that this can take some time as it will configure Couchbase Server with all the required test data (e.g. travel-sample bucket) for the examples to run successfully.
-
If you run
docker ps
in a separate shell you should see a container calledcb-test
running.
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6fe1830a205a couchbase:cb7-sdk3-java-ub20 "/entrypoint.sh couc…" About an hour ago Up About an hour 11207/tcp, 11210-11211/tcp, 0.0.0.0:8091-8096->8091-8096/tcp, 18091-18096/tcp cb-test
-
Once the container is up you can run
make TEST_NAME="StartUsing.java" single-test
to run an individual test. -
You should expect to see the following output in your shell:
✓ [hello-world] - StartUsing.java [13192]
1 test, 0 failures in 13 seconds
-
If you want to run all the code sample tests you can also execute
make tests
. -
To stop the docker container you can simply run
make cb-stop
, this will stop and remove the docker container, but will keep the local image should you need to start it up again.
Tip
|
Because we mount the project directory in the cb-test container, you will see your local code changes reflected in the container instantly, so there is no need to stop and start the container when debugging your code.
|
Creating a new test
If you look at the /modules/test
directory you will find files with the .bats extension, which are essentially our test files.
Depending on where your code sample is going to be located (e.g. /modules/devguide
), you will see a corresponding test file in the test directory.
This is mainly to keep the tests organised and easy to find.
Here is an example test case:
@test "[hello-world] - your-example-file.java" {
runExample <your-example-class-name>
assert_success
assert_output --partial "some assertion substring"
}
runExample is simply a helper function provided in test_helper.bash
, which takes care of invoking your mvn compile exec:java
command. The idea is that any generic test functions can be placed there to be used across any test.
assert_success is a helper function provied by the bats-assert
library and checks whether your command has successfully exited with a status of 0.
If not, it will fail the test.
assert_output --partial is another bats-assert helper that checks if the output of your code sample contains the substring provided. The assertion will fail if the string is not found.
Note that it will not always be necessary to assert the output of your code sample, in those cases just using assert_success
will be enough.
CI - Github Actions
When submitting a PR, the code sample tests will run against your changes in the same manner as your local machine using Github Actions.
You can see the workflow definitions in the .github
folder.