Merge branch 'port-mapping-zero'

README.rst

@@ -74,6 +74,11 @@ The ``[docker:container-name]`` section may contain the following directives:
     ``<container_name>_HOST`` is set for the test run, indicating the host
     name or IP address to use to communicate with the container.
 
+    If you set the ``HOST_PORT`` to zero, a random available port will be
+    assigned on the tox host. This is useful in case the container does not
+    ``EXPOSE`` the port you need, or if you want to map only some of the
+    ``EXPOSE``\d ports.
+
     In both environment variables, the container name part is converted to
     upper case, and all non-alphanumeric characters are replaced with an
     underscore (``_``).

tox.ini

@@ -45,6 +45,9 @@ commands =
 
 [docker:networking-one]
 image = ksdn117/tcp-udp-test
+ports =
+    0:1234/tcp
+    0:5678/udp
 
 [docker:networking-two]
 # along with networking-one, proves we can run multiple copies of the same image

tox_docker/tests/test_ports.py

@@ -15,3 +15,9 @@ def test_it_exposes_only_specified_port() -> None:
     # this container remaps 1234/tcp to 2345, and hides 5678/udp
     assert os.environ["NETWORKING_TWO_1234_TCP_PORT"] == "2345"
     assert "NETWORKING_TWO_5678_UDP_PORT" not in os.environ
+
+
+def test_docker_picks_a_port_when_you_map_to_zero() -> None:
+    # tox.ini has `ports = 0:1234/tcp 0:5678/udp`
+    assert os.environ["NETWORKING_ONE_1234_TCP_PORT"] != "0"
+    assert os.environ["NETWORKING_ONE_5678_UDP_PORT"] != "0"