{"id":13792756,"url":"https://github.com/tarantool/testcontainers-java-tarantool","last_synced_at":"2025-04-14T15:13:03.840Z","repository":{"id":40242507,"uuid":"298196544","full_name":"tarantool/testcontainers-java-tarantool","owner":"tarantool","description":"Special testcontainers for Tarantool and Tarantool Cartridge","archived":false,"fork":false,"pushed_at":"2024-05-07T10:15:59.000Z","size":356,"stargazers_count":7,"open_issues_count":4,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-14T15:12:48.086Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarantool.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-24T07:06:01.000Z","updated_at":"2024-05-07T10:16:03.000Z","dependencies_parsed_at":"2023-11-09T13:36:36.012Z","dependency_job_id":"53592d8f-413e-49a7-b09e-031bbbc7bf0e","html_url":"https://github.com/tarantool/testcontainers-java-tarantool","commit_stats":null,"previous_names":["tarantool/testcontainers-java-tarantool","tarantool/cartridge-java-testcontainers"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Ftestcontainers-java-tarantool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Ftestcontainers-java-tarantool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Ftestcontainers-java-tarantool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Ftestcontainers-java-tarantool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/testcontainers-java-tarantool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248904637,"owners_count":21180835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T22:01:15.674Z","updated_at":"2025-04-14T15:13:03.797Z","avatar_url":"https://github.com/tarantool.png","language":"Java","funding_links":[],"categories":["Connectors"],"sub_categories":["Java Ecosystem"],"readme":"# TestContainers Tarantool module\n\n[![tests](https://github.com/tarantool/testcontainers-java-tarantool/actions/workflows/tests.yml/badge.svg)](https://github.com/tarantool/testcontainers-java-tarantool/actions/workflows/tests.yml)\n\nTestcontainers module for the [Tarantool](https://tarantool.io) database and application server and the [Tarantool Cartridge](https://tarantool.io/cartridge) framework.\n\nSee [testcontainers.org](https://www.testcontainers.org) for more information about TestContainers.\n\n## Installation\n\nAdd the Maven dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.tarantool\u003c/groupId\u003e\n  \u003cartifactId\u003etestcontainers-java-tarantool\u003c/artifactId\u003e\n  \u003cversion\u003e1.3.3\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage Example\n\n### Standalone Tarantool server\n\nFor default setup, you need to have a file `server.lua` in your `src/test/resources` folder with contents similar to\nthe following:\n\n```lua\nbox.cfg {\n    listen = 3301,\n    memtx_memory = 128 * 1024 * 1024, -- 128 Mb\n    -- log = 'file:/tmp/tarantool.log',\n    log_level = 6,\n}\n-- API user will be able to login with this password\nbox.schema.user.create('api_user', { password = 'secret' })\n-- API user will be able to create spaces, add or remove data, execute functions\nbox.schema.user.grant('api_user', 'read,write,execute', 'universe')\n```\n\nThe most necessary part is exposing the port 3301 for external connections -- the container will not start without that\nsetting in the startup script.\n\nInstantiate a generic TarantoolContainer and use it in your tests:\n\n```java\npublic class SomeTest {\n\n    @ClassRule\n    static TarantoolContainer container = new TarantoolContainer();\n\n    @BeforeAll\n    public void setUp() {\n        // Run some setup commands\n        container.executeCommand(\"return 1, 2\");\n        // Or execute a script\n        container.executeScript(\"org/testcontainers/containers/test.lua\");\n    }\n\n    @Test\n    public void testSomething() throws Exception {\n\n        // Use properties provided by the container\n        TarantoolCredentials credentials =\n            new SimpleTarantoolCredentials(container.getUsername(), container.getPassword());\n        TarantoolServerAddress serverAddress =\n            new TarantoolServerAddress(container.getHost(), container.getPort());\n\n        // Create TarantoolClient instance and use it in tests\n        try (ClusterTarantoolTupleClient client = new ClusterTarantoolTupleClient(credentials, serverAddress)) {\n            Optional\u003cTarantoolSpaceMetadata\u003e spaceMetadata = client.metadata().getSpaceByName(\"test\");\n            ...\n\n            // Execute some commands in Tarantool instance for verification\n            List\u003cObject\u003e result = container.executeCommand(\"return 1, 2\");\n            ...\n        }\n    ...\n```\n\n### Tarantool Cartridge cluster\n\nFor testing against Tarantool Cartridge you need to place a directory with the application code into the classpath\n(for example, into src/test/resources directory). Suppose we have the following directory structure in there:\n\n```tree\nsrc/test/resources/\n├── cartridge\n│   ├── Dockerfile.build.cartridge\n│   ├── Dockerfile.cartridge\n│   ├── app\n│   │   └── roles\n│   │       ├── api_router.lua\n│   │       ├── api_storage.lua\n│   │       └── custom.lua\n│   ├── cartridge.post-build\n│   ├── cartridge.pre-build\n│   ├── deps.sh\n│   ├── init.lua\n│   ├── instances.yml\n│   ├── stateboard.init.lua\n│   ├── test\n│   │   ├── helper\n│   │   │   ├── integration.lua\n│   │   │   └── unit.lua\n│   │   ├── helper.lua\n│   │   ├── integration\n│   │   │   └── api_test.lua\n│   │   └── unit\n│   │       └── sample_test.lua\n│   ├── testapp-scm-1.rockspec\n│   ├── tmp\n│   └── topology.lua\n```\n\nThe file `instances.yml` contains the Cartridge nodes configuration, which looks like this:\n\n```yaml\ntestapp.router:\n  advertise_uri: localhost:3301\n  http_port: 8081\n\ntestapp.s1-master:\n  advertise_uri: localhost:3302\n  http_port: 8082\n\ntestapp.s1-replica:\n  advertise_uri: localhost:3303\n  http_port: 8083\n\ntestapp.s2-master:\n  advertise_uri: localhost:3304\n  http_port: 8084\n\ntestapp.s2-replica:\n  advertise_uri: localhost:3305\n  http_port: 8085\n```\n\nand the file `topology.lua` contains a custom script which sets up the cluster topology using the Cartridge API:\n\n```lua\ncartridge = require('cartridge')\nreplicasets = {{\n    alias = 'app-router',\n    roles = {'vshard-router', 'app.roles.custom', 'app.roles.api_router'},\n    join_servers = {{uri = 'localhost:3301'}}\n}, {\n    alias = 's1-storage',\n    roles = {'vshard-storage', 'app.roles.api_storage'},\n    join_servers = {{uri = 'localhost:3302'}, {uri = 'localhost:3303'}}\n}, {\n    alias = 's2-storage',\n    roles = {'vshard-storage', 'app.roles.api_storage'},\n    join_servers = {{uri = 'localhost:3304'}, {uri = 'localhost:3305'}}\n}}\nreturn cartridge.admin_edit_topology({replicasets = replicasets})\n```\n\nNow we can set up a Cartridge container for tests:\n\n```java\n@Testcontainers\npublic class SomeOtherTest {\n\n    @Container\n    private static final TarantoolCartridgeContainer container =\n        // Pass the classpath-relative paths of the instances configuration and topology script files\n        new TarantoolCartridgeContainer(\"cartridge/instances.yml\", \"cartridge/topology.lua\")\n            // Tarantool URI, optional. Default is \"localhost\"\n            .withRouterHost(\"localhost\")\n            // Binary port, optional. Default is 3301\n            .withRouterPort(3301)\n            // Cartridge HTTP API port, optional, 8081 is default\n            .withAPIPort(8801)\n            // Specify the actual username, default is \"admin\"\n            .withRouterUsername(\"admin\")\n            // Specify the actual password, see the \"cluster_cookie\" parameter\n            // in the cartridge.cfg({...}) call in your application.\n            // Usually it can be found in the init.lua module\n            .withRouterPassword(\"secret-cluster-cookie\")\n            // allows to reuse the container build once for faster testing\n            .withReuse(true); \n\n    // Use the created container in tests\n    public void testFoo() {\n        // Execute Lua commands in the router instance\n        List\u003cObject\u003e result = container.executeCommand(\"return profile_get(1)\");\n\n        // Instantiate a client connected to the router node\n        TarantoolCredentials credentials = new SimpleTarantoolCredentials(getRouterUsername(), getRouterPassword());\n        TarantoolServerAddress address = new TarantoolServerAddress(getRouterHost(), getRouterPort());\n        TarantoolClientConfig config = TarantoolClientConfig.builder().withCredentials(credentials).build();\n        try (ClusterTarantoolTupleClient client = new ClusterTarantoolTupleClient(config, address)) {\n            // Do something with the client...\n        }\n    }\n```\n\n##### Environment variables of cartridge container and build arguments:\n###### Build arguments:\n\nThis section describes the Docker image build arguments and environment variables inside the container. It is worth \nnothing that almost all build arguments listed here are passed into environment variables of the same name. At the \nmoment, the following arguments are available to build the image:\n\n- `CARTRIDGE_SRC_DIR` - directory on the host machine that contains all the .lua scripts needed to initialize and run \ncartridge. Defaults is `cartridge`. **Only as a build argument.**\n- `TARANTOOL_WORKDIR` - a directory where all data will be stored: snapshots, wal logs and cartridge config files. \nDefaults is `/app`. Converts to an environment variable. It is not recommended to override via the `withEnv(...)` method.\n- `TARANTOOL_RUNDIR` -  a directory where PID and socket files are stored. Defaults is `/tmp/run`. Converts to an \nenvironment variable. It is not recommended to override via the `withEnv(...)` method.\n- `TARANTOOL_DATADIR` - a directory containing the instances working directories. Defaults is `/tmp/data`. Converts to \nan environment variable. It is not recommended to override via the `withEnv(...)` method.\n- `TARANTOOL_LOGDIR` - the directory where log files are stored. Defaults is `/tmp/log`. Converts to an environment \n- variable. It is not recommended to override via the `withEnv(...)` method.\n- `TARANTOOL_INSTANCES_FILE` - path to the configuration file. Defaults is `./instances.yml`. Converts to an environment\nvariable. It is not recommended to override via the `withEnv(...)` method.\n- `START_DELAY` - the time after which cartridge will actually run after the container has started. Converts to an \nenvironment variable. It is not recommended to override via the `withEnv(...)` method.\n\nYou can set the Docker image build arguments using a map, which is passed as an input argument to the constructor when\ncreating a container in Java code. See example: https://github.com/tarantool/testcontainers-java-tarantool/blob/355d1e985bd10beca83bc7ca77f919a288709419/src/test/java/org/testcontainers/containers/TarantoolCartridgeBootstrapFromLuaWithFixedPortsTest.java#L111-L119\n\n###### Environment variables:\n\nTo set an environment variable, use the `withEnv(...)` method of testcontainers API. Full list of variables the \nenvironments used in cartridge can be found here [link](https://www.tarantool.io/ru/doc/2.11/book/cartridge/cartridge_api/modules/cartridge/#cfg-opts-box-opts).\n\n***Note:*** As shown in the previous section, some build arguments are converted to environment variables and used to\ncartridge build at the image build stage.\n\nAn example of how to set the `TARANTOOL_CLUSTER_COOKIE` parameter: https://github.com/tarantool/testcontainers-java-tarantool/blob/355d1e985bd10beca83bc7ca77f919a288709419/src/test/java/org/testcontainers/containers/TarantoolCartridgeBootstrapFromLuaWithFixedPortsTest.java#L57-L82\n\n##### Mapping ports\n\nOften there is a need to connect to a container through a specific port. To achieve this goal it is necessary\nto know the mapped port specified in the Java code. To get the mapped port, use the getMappedPort(...)` method of\ntestcontainers API. See examples: https://github.com/tarantool/testcontainers-java-tarantool/blob/ae580cb59d4621d7c11e5f80c394ec141d4c92b3/src/test/java/org/testcontainers/containers/TarantoolCartridgePortMappingTest.java#L22-L98\n\n\n## License\n\nSee [LICENSE](LICENSE).\n\n## Copyright\n\nCopyright (c) 2020 Alexey Kuzin and other authors.\n\nSee [AUTHORS](AUTHORS) for contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Ftestcontainers-java-tarantool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Ftestcontainers-java-tarantool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Ftestcontainers-java-tarantool/lists"}