Hi Erik. Glad to hear that you're digging into the code. When you find confusing bits feel free to revise the comments (if you find it to be confusing then it's quite likely others will too - admittedly the dance with the settings.cfg isn't the most straight forward code).

In run_tests.py, under the if statement that catches the case of integration tests (line 268), there is a block of code that contains a number of references to 'targets.' To start, could you explain the formatting and specific purpose of the settings.cfg file?

When running the integration tests you can provide them a set of 'targets' which are use cases that it should test, or attributes that we want to test with. When you run 'run_tests.py --help' you'll get a listing of the targets. The ones that start with "RUN_" configure the tor instance that you're running tests against and the others are attributes to augment a test instance with (for instance, making it behave as if it's in a chroot environment).

The settings.cfg [1] is a configuration file that contains stuff that I don't want to hardcode into the source. For instance, the text that you get when running 'run_tests.py --help'. It also contains a mapping between testing targets and the torrc attributes that they should have. The "RUN_PASSWORD", for instance, is a target and the "PORT, PASSWORD" are enumerations that are translated into real configuration values by the runner [2].

For a description of the settings.cfg format see... http://www.atagar.com/transfer/tmp/stem_html_12_06_05/stem.util.html

Hopefully this makes a bit more sense now. If it doesn't then let me know what you still find to be confusing.

Cheers! -Damian

[1] https://gitweb.torproject.org/stem.git/blob/HEAD:/test/settings.cfg [2] https://gitweb.torproject.org/stem.git/blob/HEAD:/test/runner.py#l81