Embedded Consul
Embedded Consul provides easy way to run Consul in integration tests.
Built on Consul 1.8.6
Compatible with jdk1.8+.
Working on all operating systems: Mac, Linux, Windows.
How to get it?
<dependency>
<groupId>com.pszymczyk.consul</groupId>
<artifactId>embedded-consul</artifactId>
<version>2.2.1</version>
<scope>test</scope>
</dependency>
testImplementation 'com.pszymczyk.consul:embedded-consul:2.2.1'
Usage
Spring Boot setup
@RunWith(SpringRunner.class)
@SpringBootTest
public class SpringBootIntegrationTest {
@BeforeClass
public static void setup() {
consul = ConsulStarterBuilder.consulStarter().buildAndStart();
System.setProperty("spring.cloud.consul.enabled", "true");
System.setProperty("spring.cloud.consul.host", "localhost");
System.setProperty("spring.cloud.consul.port", String.valueOf(consul.getHttpPort()));
}
@Test
public void doSomethingWithSpring(){
//use your spring beans
}
}
JUnit Rule
If JUnit is on classpath, simplest way to use embedded-consul is via
JUnit rules.
public class IntegrationTest {
@ClassRule
public static final ConsulResource consul = new ConsulResource();
private OkHttpClient client = new OkHttpClient();
@Test
public void shouldStartConsul() throws Throwable {
await().atMost(30, TimeUnit.SECONDS).until(() -> {
Request request = new Request.Builder()
.url("http://localhost:" + consul.getHttpPort() + "/v1/agent/self")
.build();
return client.newCall(request).execute().code() == 200;
});
}
}
JUnit 5 Extension
There is also an extension for JUnit 5.
Unlike in Junit 4 with @Rule and @ClassRule there is no option to control the scope of ConsulProcess.
ConsulExtension starts Consul for a whole class just like @ClassRule, but it resets the Consul state between tests.
class IntegrationTest {
@RegisterExtension
ConsulExtension consul = new ConsulExtension();
private OkHttpClient client = new OkHttpClient();
@Test
void shouldStartConsul() throws Throwable {
await().atMost(30, TimeUnit.SECONDS).until(() -> {
Request request = new Request.Builder()
.url("http://localhost:" + consul.getHttpPort() + "/v1/agent/self")
.build();
return client.newCall(request).execute().code() == 200;
});
}
}
The extension can also be registered via @ExtendWith annotation and provided to test as a method argument.
@ExtendWith(ConsulExtension.class)
class IntegrationTest {
@Test
void test(ConsulProcess consul) {
OkHttpClient client = new OkHttpClient();
await().atMost(30, TimeUnit.SECONDS).until(() -> {
Request request = new Request.Builder()
.url("http://localhost:" + consul.getHttpPort() + "/v1/agent/self")
.build();
return client.newCall(request).execute().code() == 200;
});
}
}
Manual
public class IntegrationTest {
private ConsulProcess consul;
@Before
public void setup() {
consul = ConsulStarterBuilder.consulStarter().buildAndStart();
}
@After
public void cleanup() throws Exception {
consul.close();
}
/* tests as in example above */
Register Services
You can automatically register Services in Consul via ConsulStarterBuilder.
ConsulStarterBuilder.consulStarter()
.withService(
new Service("a service"),
new Service("another service", "127.0.0.1", 8000));
.buildAndStart();
Reset Consul state
The ConsulProcess can be reset at any time. Reset method do few operations:
- removing all registered services
- removes all registered checks
- removes all data from kv store
- destroy all active sessions
Invoking reset method is faster than starting new Consul process.
consulClient.setKVBinaryValue("foo", "bar".getBytes())
// do sth
consul.reset()
assert consulClient.getKVBinaryValue("foo").getValue() == null
Passing custom configuration
If you want to pass custom property which is not covered by ConsulStartrBuilder you can pass JSON configuration.
String customConfiguration =
"{" +
"\"datacenter\": \"test-dc\"," +
"\"log_level\": \"INFO\"," +
"\"node_name\": \"foobar\"" +
"}";
ConsulProcess consul = ConsulStarterBuilder.consulStarter().withCustomConfig(customConfiguration).buildAndStart();
Given JSON configuration will be saved in addition configuration file extra_config.json and processed after base
configuration (with highest priority).
Changing download directory
An environment variable can be set to change the consul CDN.
# default
export CONSUL_BINARY_CDN=https://releases.hashicorp.com/consul/
Proxy can be used if necessary.
https.proxyHost=localhost
https.proxyPort=3128
Files structure
├─$temp-directory
│
├── embedded-consul-$consul-version
│ ├── consul
│ └── consul.zip
├── embedded-consul-data-dir + randomNumber
│ ├── raft
│ │ ├── peers.json
│ │ ├── raft.db
│ │ └── snapshots
│ └── serf
│ ├── local.snapshot
│ └── remote.snapshot
├── embedded-consul-config-dir + randomNumber
│ ├── basic_config.json
│ └── extra_config.json
To avoid unnecessary downloads Consul binary is downloaded into static named directory /$tmp/embedded-consul-$consul-version.
Another stuff (ports config, raft, serf) is created in dynamically named temp directories.
At the moment files are not deleted!.
Simultaneous running
Embedded Consul overrides all default ports used by Consul.
Ports are randomized so it's possible to run multiple Consul Agents in single machine.
Configuration file is stored in /$tmp/embedded-consul-config-dir$randomNumber/basic_config.json, sample content:
{
"ports": {
"dns": 50084,
"serf_lan": 50085,
"serf_wan": 50086,
"server": 50087
},
"disable_update_check": true,
"performance": {
"raft_multiplier": 1
}
}
JDK 1.7.x support
Support for older Java versions has been dropped throughout release 2.0.0.
If you'd like to use embedded-consul with JDK 1.7 the 1.1.1 is the last appropriate version.
