# -*-mode: doctest; tab-width: 0; py-indent-offset: 4; coding: utf-8-unix -*-

== stem_examples tor testing ==

This is a Python doctest file that is executable documentation.

Pass the controller password if needed as an environment variable:

    >>> import os
    >>> assert os.environ['TOR_CONTROLLER_PASSWORD']
    
Add our code to the PYTHONPATH 
    >>> import sys
    >>> sys.path.append(os.path.join(os.getcwd(), 'src', 'stem_examples'))

We'll need the settings defined in  {{{/usr/local/etc/testforge/testforge.yml}}}

    >>> print("yaml", file=sys.stderr)
    >>> import yaml
    >>> sFacts = open('/usr/local/etc/testforge/testforge.yml').read()
    >>> assert sFacts
    >>> dFacts = yaml.safe_load(sFacts)

FixMe: use the settings for the ports and directories below.

    >>> import os
    >>> os.environ['http_proxy']  = 'http://'+dFacts['HTTP_PROXYHOST']+':'+str(dFacts['HTTP_PROXYPORT'])
    >>> os.environ['https_proxy'] = 'http://'+dFacts['HTTPS_PROXYHOST']+':'+str(dFacts['HTTPS_PROXYPORT'])
    >>> os.environ['socks_proxy']  = 'socks5://'+dFacts['SOCKS_PROXYHOST']+':'+str(dFacts['SOCKS_PROXYPORT'])

### compare_flags Comparing Directory Authority Flags
### introduction_points Introduction Points

    >>> print("introduction_points", file=sys.stderr)
    >>> import introduction_points

The introduction points are the ways of connecting to hidden services.
We test 3 known hidden services: Facebook, DuckDuckGo and .

   >>> lKNOWN_ONIONS = [
   ...  'facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd', # facebook
   ...  'duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad', # ddg
   ...  'zkaan2xfbuxia2wpf7ofnkbz6r5zdbbvxbunvp5g2iebopbfc4iqmbad', # hks
   ... ]

We wil expect to get back the hidden service version, the descriptor-lifetime
and then the descriptor-signing-key-cert:

    >>> introduction_points.iMain(lKNOWN_ONIONS) #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
    hs-descriptor 3
    descriptor-lifetime ...
    <BLANKLINE>
    
### exit_used Determine The Exit You're Using

Lets say you're using Tor and one day you run into something odd. Maybe a
misconfigured relay, or maybe one that's being malicious.
How can you figure out what exit you're using?

    >>> print("exit_used", file=sys.stderr)
    >>> import exit_used

## relay_connections Connection Summary

    >>> print("relay_connections", file=sys.stderr)
    >>> import relay_connections

The following provides a summary of your relay's inbound and outbound connections.
You must be root or tor to run this:
relay_connections.iMain(["--ctrlport", "9051"])

## outdated_relays

    >>> print("outdated_relays", file=sys.stderr)
    >>> import outdated_relays
    >>> outdated_relays.iMain() #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
    Checking for outdated relays ...
    <BLANKLINE>

## tor_bootstrap_check

    >>> print("tor_bootstrap_check", file=sys.stderr)
    >>> import tor_bootstrap_check

A script by adrelanos@riseup.net to check what percentage of boostrapping
tor is at. This fails under doctest but not from the cmdline

>> tor_bootstrap_check.iMain() #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
NOTICE ...
<BLANKLINE>

    control_port = stem.socket.ControlPort(address, port)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/stem/socket.py", line 503, in __init__
    self.connect()
  File "/usr/local/lib/python3.11/site-packages/stem/socket.py", line 172, in connect
    self._socket = self._make_socket()
                   ^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/stem/socket.py", line 538, in _make_socket
    raise stem.SocketError(exc)
stem.SocketError: Socket error: 0x01: General SOCKS server failure