Adds docs/integration-test.md by chernser · Pull Request #3133 · ClickHouse/clickhouse-java

chernser · 2026-09-15T21:43:59Z

Summary

Adds docs/integration-test.md that describes testing strategies of different areas when integrating with client or JDBC driver.

Checklist

Delete items not relevant to your PR:

Closes #
Unit and integration tests covering the common scenarios were added
A human-readable description of the changes was provided to include in CHANGELOG
For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

mshustov · 2026-09-17T08:19:47Z

+
+**Tests after Issues** 
+
+It is bad practice to make tests just to verify some issue - always bound tests to a feature or a function. This help to verify test correctnes in the future.  


It can be read as don't write tests for a regression, I'd rephrase to organize the test by the behavior it verifies

here I want to say - don't write tests for a regression but for functionality. So Organize tests by functionality they verify looks what I want to say. Do you agree?

mshustov · 2026-09-17T08:21:30Z

+- How application performance degrade with load.
+- Estimate needed resources.
+
+Load tests can be done by increasing data volume or (if applicable) growth of concurent requests. Test with multiple load of big datasets in same instance if applicable. 


are you hinting towards testing a multi-tenant and noisy neighboor scenarios? let's just call it out

mshustov · 2026-09-17T08:21:54Z

+
+Tests have great value as a contract verification tool when built properly. If there are tests for other integrations, we recommend porting them to verify ClickHouse integration.
+
+# General Recommendations


should be h2? here and below

I'll review headings.

mshustov · 2026-09-17T08:22:47Z

+
+## Environment
+
+Tests can be run in different environments: local, staging, production. Running tests locally is mainly for development and are essential. ClickHouse can be easily run as Docker container (see below). Tests running on staging environment is more important because they verify real systems integration. ClickHouse Cloud is cost effective so 


the section is a bit hard to grasp since the project itself (or Clickhouse Cloud) do not have a notion of different environments

This is about test environment. I will clarify.

mshustov · 2026-09-17T08:23:43Z

@@ -0,0 +1,116 @@
+# ClickHouse Java Client & JDBC Driver Integration Testing


what pages should link to this page?

good call - both integration-jdbc and integration-client.

mshustov · 2026-09-17T08:24:52Z

+
+**Example: Running ClickHouse in Docker**
+
+Start a local ClickHouse instance for testing:


I'd propose splitting Cloud and OSS sub-sections. For OSS, I'd include an example with a cluster topology

mshustov · 2026-09-17T08:25:57Z

+- Value boundaries - does client allow set extreme value that you have in your design. 
+- Invalid values - does application stop them before passing to the client, does client handle them in way you expect.
+- ClickHouse settings - are they correctly passed from user to database. 
+- Timeouts - do they have effect and passed in correct units (most common mistake).  


for Cloud, I'd propose adding testing for idling, different authc methods

good point. But this is also true for OSS

mshustov · 2026-09-17T08:26:59Z

+
+## Abstract
+
+Integration testing essential in building integrations. Scope of it defines quality of service for end users. Each business case has own test goals along with 


Suggested change

Integration testing essential in building integrations. Scope of it defines quality of service for end users. Each business case has own test goals along with

Integration testing is essential in building integrations. Scope of it defines quality of service for end users. Each business case has own test goals along with

Could you run a proof-reader against the doc?

chernser added 2 commits September 11, 2026 23:14

Added integration-testing.md initial version

49a77b3

Completed initial version of integration-test.md

f562a6d

chernser requested a review from mzitnik as a code owner September 15, 2026 21:44

mshustov approved these changes Sep 17, 2026

View reviewed changes


		Tests after Issues

		It is bad practice to make tests just to verify some issue - always bound tests to a feature or a function. This help to verify test correctnes in the future.


		Tests have great value as a contract verification tool when built properly. If there are tests for other integrations, we recommend porting them to verify ClickHouse integration.

		# General Recommendations


		## Environment

		Tests can be run in different environments: local, staging, production. Running tests locally is mainly for development and are essential. ClickHouse can be easily run as Docker container (see below). Tests running on staging environment is more important because they verify real systems integration. ClickHouse Cloud is cost effective so

		@@ -0,0 +1,116 @@
		# ClickHouse Java Client & JDBC Driver Integration Testing


		Example: Running ClickHouse in Docker

		Start a local ClickHouse instance for testing:


		## Abstract

		Integration testing essential in building integrations. Scope of it defines quality of service for end users. Each business case has own test goals along with

	Integration testing essential in building integrations. Scope of it defines quality of service for end users. Each business case has own test goals along with
	Integration testing is essential in building integrations. Scope of it defines quality of service for end users. Each business case has own test goals along with

Conversation

chernser commented Sep 15, 2026

Summary

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants