healthcheck test silently ignored when of wrong type

Bug, affected versions:

• docker-py: 4.1.0
• docker-ce: 19.03.8

Summary

healtcheck['test'] is implicitly expected to be a str, and the API not only does not complain if it is a list, but just seemingly ignores it without any effect. The documentation is not very generous, it only mentions healthcheck has to be a dict.

How to reproduce:

from docker import from_env

containers = from_env().containers

args = ['alpine', ['sh']]
kwargs = {'tty': True, 'detach': True, 'healthcheck': {'test': 'true'}}

good = containers.run(*args, **kwargs)
assert 'Health' not in good.attrs['State']
good.reload()
assert 'Health' in good.attrs['State']

kwargs['healthcheck']['test'] = ['true']

bad = containers.run(*args, **kwargs)
assert 'Health' not in bad.attrs['State']
bad.reload()
assert 'Health' in bad.attrs['State']

Proposed fix

1. assert healthcheck['test'] type is a str
2. document healthcheck keys

When encountering this behavior I was still under the (wrong) impression that dockerfile HEALTHCHECK can be also defined as a list, just like CMD. So you might not consider this a bug and that's fine. If you do however, I will request a pull once I get some free time.

Start with the containers.run reproduction in the issue, comparing string and list values for healthcheck['test']. Trace how the healthcheck argument is handled, then verify that an invalid list is rejected and that the documented healthcheck keys describe the accepted input.