testcontainers-core 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 584f5aabce655fd2f113af37af6ce59cc8b3e0f6aa4b276bff52378e1d3c5e9d
-  data.tar.gz: 0a3c73c6a6ba495c61b3ded68092d4a58a06099e1ff543d7ac2a45e9503082a6
+  metadata.gz: a5422789f7d26555fc9198f71b189ec3f75beba0dbaed0b66f541ef5513a9819
+  data.tar.gz: abd82854569df36e3581edc1eb6460af76f2cb3b570ec711131f24f351568f56
 SHA512:
-  metadata.gz: 18f526847480a5cec71aa4abf2b10393fa7a08ccf5c4f70a07c18667624a8fb49ca3f0d9d241f0f5dd9e32404f3e0e06fc2cb67465059703d5e9eec143c04f4e
-  data.tar.gz: fcc6793d0bbdf773de7e0cb5933364f45840c034c8821dd12ab99c17d08a05c23967d2b992d4152b2c7298eae12d75d751eaff8e83e21563a060647cdcbd1b67
+  metadata.gz: 7eebf9df18f1599e5a13928f163a5269b5b0e78297447ff04396db804bfe7f0ff2515b16da13180e504905bf81d533d9528d76bae8f52d2d55d4823d69aed209
+  data.tar.gz: 97461a668a41d5efb9c3c88cac46d2f4f308a5975bff34042bb78a7edf41b66a2f2a3426ffa8a39baa0efe6b70bc8949306e8372d40dc35a80e4ecd12b2e0574

data/CHANGELOG.md

@@ -1,6 +1,35 @@
+## [0.2.0] - 2024-02-08
+
+### Added
+
+- DockerContainer#new now accepts optional keyword argument `image_create_options` which accepts a hash. Passes the options to `Docker::Image.create`. See the [Docker ImageCreate api](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageCreate) for available parameters.
+
+- DockerContainer#remove now accepts an optional options hash. See the [Docker ContainerDelete api](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerDelete) for available parameters.
+
+## [0.1.3] - 2023-06-10
+
+### Added
+
+- Support for entrypoint customization and the DockerContainer#with_entrypoint method
+
+- Methods to read/write strings from and to containers: read_file, store_file
+
+- Methods to copy files from and to containers: copy_file_from_container, copy_file_to_container
+
+- Support for waiting strategies on start
+
+- DockerContainer#with_exposed_port (singular) for convenience
+
+- GenericContainer as alias for DockerContainer
+
+### Fixed
+
+- DockerContainer#add_exposed_ports don't override PortBinding settings added by #add_fixed_exposed_port
+
+
 ## [0.1.2] - 2023-05-13
 
-## Added
+### Added
 
 - DockerContainer#first_mapped_port method returns the first of the
   mapped ports for convenience.
@@ -13,11 +42,11 @@
 
   redis_container.with_healthcheck(test: ["redis-cli ping"], interval: 30, timeout: 30, retries: 3)
 
-## Changed
+### Changed
 
 - DockerContainer#mapped_port(port) method now returns an Integer instead of a String.
 
-## Fixed
+### Fixed
 
 - Links to the GitHub project on the README.md file are fixed.
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    testcontainers-core (0.1.1)
+    testcontainers-core (0.2.0)
       docker-api (~> 2.2)
 
 GEM
@@ -57,6 +57,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-21
+  ruby
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -28,7 +28,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/guilleiguaran/testcontainers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/guilleiguaran/testcontainers/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/testcontainers/testcontainers-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/testcontainers/testcontainers-ruby/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -36,4 +36,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Testcontainers project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/guilleiguaran/testcontainers/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Testcontainers project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/testcontainers/testcontainers-ruby/blob/main/CODE_OF_CONDUCT.md).

data/lib/testcontainers/docker_container.rb

@@ -6,6 +6,7 @@ module Testcontainers
   # @attr name [String] the container's name
   # @attr image [String] the container's image name
   # @attr command [Array<String>, nil] the command to run in the container
+  # @attr entrypoint [Array<String>, nil] the entrypoint to run in the container
   # @attr exposed_ports [Hash, nil] a hash mapping exposed container ports to an empty hash (used for Docker API compatibility)
   # @attr port_bindings [Hash, nil] a hash mapping container ports to host port bindings (used for Docker API compatibility)
   # @attr volumes [Hash, nil] a hash mapping volume paths in the container to an empty hash (used for Docker API compatibility)
@@ -18,7 +19,8 @@ module Testcontainers
   # @attr_reader _container [Docker::Container, nil] the underlying Docker::Container object
   # @attr_reader _id [String, nil] the container's ID
   class DockerContainer
-    attr_accessor :name, :image, :command, :exposed_ports, :port_bindings, :volumes, :filesystem_binds, :env, :labels, :working_dir, :healthcheck
+    attr_accessor :name, :image, :command, :entrypoint, :exposed_ports, :port_bindings, :volumes, :filesystem_binds,
+      :env, :labels, :working_dir, :healthcheck, :wait_for
     attr_accessor :logger
     attr_reader :_container, :_id
 
@@ -28,6 +30,7 @@ module Testcontainers
     # @param command [Array<String>, nil] the command to run in the container
     # @param name [String, nil] the container's name
     # @param exposed_ports [Hash, Array<String>, nil] a hash or an array of exposed container ports
+    # @param image_create_options [Hash] a hash of options to pass to Docker::Image.create.
     # @param port_bindings [Hash, Array<String>, nil] a hash or an array of container ports to host port bindings
     # @param volumes [Hash, Array<String>, nil] a hash or an array of volume paths in the container
     # @param filesystem_binds [Array<String>, Hash, nil] an array of strings or a hash representing bind mounts from the host to the container
@@ -35,13 +38,15 @@ module Testcontainers
     # @param labels [Hash, nil] a hash of labels to be applied to the container
     # @param working_dir [String, nil] the working directory for the container
     # @param logger [Logger] a logger instance for the container
-    def initialize(image, command: nil, name: nil, exposed_ports: nil, port_bindings: nil, volumes: nil, filesystem_binds: nil, env: nil,
-      labels: nil, working_dir: nil, healthcheck: nil, logger: Testcontainers.logger)
+    def initialize(image, name: nil, command: nil, entrypoint: nil, exposed_ports: nil, image_create_options: {}, port_bindings: nil, volumes: nil, filesystem_binds: nil,
+      env: nil, labels: nil, working_dir: nil, healthcheck: nil, wait_for: nil, logger: Testcontainers.logger)
 
       @image = image
-      @command = command
       @name = name
+      @command = command
+      @entrypoint = entrypoint
       @exposed_ports = add_exposed_ports(exposed_ports) if exposed_ports
+      @image_create_options = image_create_options
       @port_bindings = add_fixed_exposed_ports(port_bindings) if port_bindings
       @volumes = add_volumes(volumes) if volumes
       @env = add_env(env) if env
@@ -49,6 +54,7 @@ module Testcontainers
       @labels = add_labels(labels) if labels
       @working_dir = working_dir
       @healthcheck = add_healthcheck(healthcheck) if healthcheck
+      @wait_for = add_wait_for(wait_for)
       @logger = logger
       @_container = nil
       @_id = nil
@@ -78,8 +84,8 @@ module Testcontainers
       port = normalize_port(port)
       @exposed_ports ||= {}
       @port_bindings ||= {}
-      @exposed_ports[port] = {}
-      @port_bindings[port] = [{"HostPort" => ""}]
+      @exposed_ports[port] ||= {}
+      @port_bindings[port] ||= [{"HostPort" => ""}]
       @exposed_ports
     end
 
@@ -242,6 +248,51 @@ module Testcontainers
       }
     end
 
+    # Add a wait_for strategy to the container configuration.
+    #
+    # @param method [Symbol, String, Proc, Array] The method to call on the container to wait for it to be ready.
+    # @param args [Array] The arguments to pass to the method if it is a symbol or string.
+    # @param kwargs [Hash] The keyword arguments to pass to the method if it is a symbol or string.
+    # @param block [Proc] The block to call on the container to wait for it to be ready.
+    # @return [Proc] The wait_for strategy.
+    def add_wait_for(method = nil, *args, **kwargs, &block)
+      if method.nil?
+        if block
+          if block.arity == 1
+            @wait_for = block
+          else
+            raise ArgumentError, "Invalid wait_for block: #{block}"
+          end
+        elsif @exposed_ports && !@exposed_ports.empty?
+          port = @exposed_ports.keys.first.split("/").first
+          @wait_for = ->(container) { container.wait_for_tcp_port(port) }
+        end
+      elsif method.is_a?(Proc)
+        if method.arity == 1
+          @wait_for = method
+        else
+          raise ArgumentError, "Invalid wait_for method: #{method}"
+        end
+      elsif method.is_a?(Array)
+        method_name = "wait_for_#{method[0]}".to_sym
+        args = method[1] || []
+        kwargs = method[2] || {}
+        if respond_to?(method_name)
+          @wait_for = ->(container) { container.send(method_name, *args, **kwargs) }
+        else
+          raise ArgumentError, "Invalid wait_for method: #{method_name}"
+        end
+      else
+        method_name = "wait_for_#{method}".to_sym
+        if respond_to?(method_name)
+          @wait_for = ->(container) { container.send(method_name, *args, **kwargs) }
+        else
+          raise ArgumentError, "Invalid wait_for method: #{method_name}"
+        end
+      end
+      @wait_for
+    end
+
     # Set options for the container configuration using "with_" methods.
     #
     # @param options [Hash] A hash of options where keys correspond to "with_" methods and values are the arguments for those methods.
@@ -269,6 +320,16 @@ module Testcontainers
       self
     end
 
+    # Set the entrypoint for the container.
+    #
+    # @param parts [Array<String>] The entry point for the container as an array of strings.
+    # @return [DockerContainer] The updated DockerContainer instance.
+    def with_entrypoint(*parts)
+      @entrypoint = parts.first.is_a?(Array) ? parts.first : parts
+
+      self
+    end
+
     # Set the name of the container.
     #
     # @param name [String] The name of the container.
@@ -309,6 +370,15 @@ module Testcontainers
       self
     end
 
+    # Adds a single exposed port to the container.
+    #
+    # @param port [String, Integer] The port to expose.
+    # @return [DockerContainer] The updated DockerContainer instance.
+    def with_exposed_port(port)
+      add_exposed_ports(port)
+      self
+    end
+
     # Adds a fixed exposed port to the container.
     #
     # @param container_port [String, Integer, Hash] The container port in the format "port/protocol" or as an integer.
@@ -373,6 +443,18 @@ module Testcontainers
       self
     end
 
+    # Add a wait_for strategy to the container configuration.
+    #
+    # @param method [Symbol, String, Proc, Array] The method to call on the container to wait for it to be ready.
+    # @param args [Array] The arguments to pass to the method if it is a symbol or string.
+    # @param kwargs [Hash] The keyword arguments to pass to the method if it is a symbol or string.
+    # @param block [Proc] The block to call on the container to wait for it to be ready.
+    # @return [DockerContainer] The updated DockerContainer instance.
+    def with_wait_for(method = nil, *args, **kwargs, &block)
+      add_wait_for(method, *args, **kwargs, &block)
+      self
+    end
+
     # Starts the container, yields the container instance to the block, and stops the container.
     #
     # @yield [DockerContainer] The container instance.
@@ -388,19 +470,23 @@ module Testcontainers
     #
     # @return [DockerContainer] The DockerContainer instance.
     # @raise [ConnectionError] If the connection to the Docker daemon fails.
+    # @raise [NotFoundError] If Docker is unable to find the image.
     def start
-      Docker::Image.create("fromImage" => @image)
+      Docker::Image.create({"fromImage" => @image}.merge(@image_create_options))
 
       @_container ||= Docker::Container.create(_container_create_options)
       @_container.start
 
       @_id = @_container.id
       json = @_container.json
-
       @name = json["Name"]
       @_created_at = json["Created"]
 
+      @wait_for&.call(self)
+
       self
+    rescue Docker::Error::NotFoundError => e
+      raise NotFoundError, e.message
     rescue Excon::Error::Socket => e
       raise ConnectionError, e.message
     end
@@ -449,11 +535,12 @@ module Testcontainers
 
     # Removes the container.
     #
+    # @param options [Hash] Additional options to send to the container remove command.
     # @return [DockerContainer] The DockerContainer instance.
     # @return [nil] If the container does not exist.
     # @raise [ConnectionError] If the connection to the Docker daemon fails.
-    def remove
-      @_container&.remove
+    def remove(options = {})
+      @_container&.remove(options)
       @_container = nil
       self
     rescue Excon::Error::Socket => e
@@ -651,6 +738,24 @@ module Testcontainers
       container_ports.map { |port| mapped_port(port) }.first
     end
 
+    # Returns the container's mounts.
+    #
+    # @return [Array<Hash>] An array of the container's mounts.
+    # @raise [ConnectionError] If the connection to the Docker daemon fails.
+    # @raise [ContainerNotStartedError] If the container has not been started.
+    def mounts
+      info["Mounts"]
+    end
+
+    # Returns the container's mount names.
+    #
+    # @return [Array<String>] The container's mount names.
+    # @raise [ConnectionError] If the connection to the Docker daemon fails.
+    # @raise [ContainerNotStartedError] If the container has not been started.
+    def mount_names
+      mounts.map { |mount| mount["Name"] }
+    end
+
     # Returns the value for the given environment variable.
     #
     # @param key [String] The environment variable's key.
@@ -810,6 +915,81 @@ module Testcontainers
       File.exist?("/.dockerenv")
     end
 
+    # Copies a IO object or a file from the host to the container.
+    #
+    # @param container_path [String] The path to the file inside the container.
+    # @param host_path_or_io [String, IO] The path to the file on the host or a IO object.
+    # @raise [ContainerNotStartedError] If the container has not been started.
+    # @raise [ConnectionError] If the connection to the Docker daemon fails.
+    # @return [self]
+    def copy_file_to_container(container_path, host_path_or_io)
+      raise ContainerNotStartedError, "Container has not been started" unless running?
+      raise ArgumentError, "Container path must be a non-empty string" if container_path.to_s.empty?
+
+      begin
+        io = host_path_or_io.is_a?(String) ? File.open(host_path_or_io) : host_path_or_io
+        io.rewind if io.pos != 0
+        store_file(container_path, io.read)
+        io.rewind
+      rescue => e
+        puts "Error while copying file to container: #{e.message}"
+        return false
+      ensure
+        io.close if io.respond_to?(:close)
+      end
+
+      true
+    end
+
+    # Copies a file from the container to the host.
+    #
+    # @param container_path [String] The path to the file inside the container.
+    # @param host_path_or_io [String, IO] The path to the file on the host or a IO object.
+    # @raise [ContainerNotStartedError] If the container has not been started.
+    # @raise [ConnectionError] If the connection to the Docker daemon fails.
+    # @return [String] The contents of the file inside the container.
+    def copy_file_from_container(container_path, host_path_or_io)
+      raise ContainerNotStartedError, "Container has not been started" unless running?
+      raise ArgumentError, "Container path must be a non-empty string" if container_path.to_s.empty?
+
+      begin
+        io = host_path_or_io.is_a?(String) ? File.open(host_path_or_io, "w") : host_path_or_io
+        io.rewind if io.pos != 0
+        content = read_file(container_path)
+        io.write(content)
+        io.rewind
+      rescue => e
+        puts "Error while copying file from container: #{e.message}"
+        raise e # Optionally re-raise the exception or handle it according to your needs
+      ensure
+        io.close if io.respond_to?(:close)
+      end
+
+      content
+    end
+
+    # Reads the contents of a file inside the container.
+    #
+    # @param path [String] The path to the file.
+    # @return [String] The contents of the file.
+    def read_file(path)
+      raise ContainerNotStartedError unless @_container
+
+      @_container.read_file(path)
+    end
+
+    # Writes the contents of a file inside the container.
+    #
+    # @param path [String] The path to the file.
+    # @param contents [String] The contents of the file.
+    # @raise [ContainerNotStartedError] If the container has not been started.
+    # @raise [ConnectionError] If the connection to the Docker daemon fails.
+    def store_file(path, contents)
+      raise ContainerNotStartedError unless @_container
+
+      @_container.store_file(path, contents)
+    end
+
     private
 
     def normalize_ports(ports)
@@ -937,6 +1117,7 @@ module Testcontainers
         "name" => @name,
         "Image" => @image,
         "Cmd" => @command,
+        "Entrypoint" => @entrypoint,
         "ExposedPorts" => @exposed_ports,
         "Volumes" => @volumes,
         "Env" => @env,
@@ -950,4 +1131,7 @@ module Testcontainers
       }.compact
     end
   end
+
+  # Alias for forward-compatibility
+  GenericContainer = DockerContainer
 end

data/lib/testcontainers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Testcontainers
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/testcontainers.rb

@@ -12,6 +12,8 @@ module Testcontainers
 
   class ConnectionError < Error; end
 
+  class NotFoundError < Error; end
+
   class TimeoutError < Error; end
 
   class ContainerNotStartedError < Error; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: testcontainers-core
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Guillermo Iguaran
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-13 00:00:00.000000000 Z
+date: 2024-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docker-api
@@ -98,13 +98,13 @@ files:
 - lib/testcontainers.rb
 - lib/testcontainers/docker_container.rb
 - lib/testcontainers/version.rb
-homepage: https://github.com/guilleiguaran/testcontainers-ruby
+homepage: https://github.com/testcontainers/testcontainers-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/guilleiguaran/testcontainers-ruby
-  source_code_uri: https://github.com/guilleiguaran/testcontainers-ruby
-  changelog_uri: https://github.com/guilleiguaran/testcontainers-ruby/blob/main/core/CHANGELOG.md
+  homepage_uri: https://github.com/testcontainers/testcontainers-ruby
+  source_code_uri: https://github.com/testcontainers/testcontainers-ruby
+  changelog_uri: https://github.com/testcontainers/testcontainers-ruby/blob/main/core/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -120,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
 summary: Testcontainers for Ruby.