def test_authenticate_general_password(self):
   """
   Tests the authenticate function's password argument.
   """
   
   if test.runner.require_control(self): return
   
   # this is a much better test if we're just using password auth, since
   # authenticate will work reguardless if there's something else to
   # authenticate with
   
   runner = test.runner.get_runner()
   tor_options = runner.get_options()
   is_password_only = test.runner.Torrc.PASSWORD in tor_options and not test.runner.Torrc.COOKIE in tor_options
   
   # tests without a password
   with runner.get_tor_socket(False) as control_socket:
     if is_password_only:
       self.assertRaises(stem.connection.MissingPassword, stem.connection.authenticate, control_socket)
     else:
       stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot())
       test.runner.exercise_controller(self, control_socket)
   
   # tests with the incorrect password
   with runner.get_tor_socket(False) as control_socket:
     if is_password_only:
       self.assertRaises(stem.connection.IncorrectPassword, stem.connection.authenticate, control_socket, "blarg")
     else:
       stem.connection.authenticate(control_socket, "blarg", runner.get_chroot())
       test.runner.exercise_controller(self, control_socket)
   
   # tests with the right password
   with runner.get_tor_socket(False) as control_socket:
     stem.connection.authenticate(control_socket, test.runner.CONTROL_PASSWORD, runner.get_chroot())
     test.runner.exercise_controller(self, control_socket)

 def assert_matches_test_config(self, protocolinfo_response):
   """
   Makes assertions that the protocolinfo response's attributes match those of
   the test configuration.
   """
   
   runner = test.runner.get_runner()
   tor_options = runner.get_options()
   auth_methods, auth_cookie_path = [], None
   
   if test.runner.Torrc.COOKIE in tor_options:
     auth_methods.append(stem.response.protocolinfo.AuthMethod.COOKIE)
     chroot_path = runner.get_chroot()
     auth_cookie_path = runner.get_auth_cookie_path()
     
     if chroot_path and auth_cookie_path.startswith(chroot_path):
       auth_cookie_path = auth_cookie_path[len(chroot_path):]
   
   if test.runner.Torrc.PASSWORD in tor_options:
     auth_methods.append(stem.response.protocolinfo.AuthMethod.PASSWORD)
   
   if not auth_methods:
     auth_methods.append(stem.response.protocolinfo.AuthMethod.NONE)
   
   self.assertEqual((), protocolinfo_response.unknown_auth_methods)
   self.assertEqual(tuple(auth_methods), protocolinfo_response.auth_methods)
   self.assertEqual(auth_cookie_path, protocolinfo_response.cookie_path)

 def test_authenticate_general_cookie(self):
   """
   Tests the authenticate function with only cookie authentication methods.
   This manipulates our PROTOCOLINFO response to test each method
   individually.
   """
   
   if test.runner.require_control(self): return
   
   runner = test.runner.get_runner()
   tor_options = runner.get_options()
   is_cookie_only = test.runner.Torrc.COOKIE in tor_options and not test.runner.Torrc.PASSWORD in tor_options
   
   # test both cookie authentication mechanisms
   with runner.get_tor_socket(False) as control_socket:
     if is_cookie_only:
       for method in (stem.connection.AuthMethod.COOKIE, stem.connection.AuthMethod.SAFECOOKIE):
         protocolinfo_response = stem.connection.get_protocolinfo(control_socket)
         
         if method in protocolinfo_response.auth_methods:
           # narrow to *only* use cookie auth or safecooke, so we exercise
           # both independently
           
           protocolinfo_response.auth_methods = (method, )
           stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot(), protocolinfo_response = protocolinfo_response)

    def test_launch_tor_with_config(self):
        """
    Exercises launch_tor_with_config.
    """

        if test.runner.only_run_once(self, "test_launch_tor_with_config"):
            return

        # Launch tor without a torrc, but with a control port. Confirms that this
        # works by checking that we're still able to access the new instance.

        runner = test.runner.get_runner()
        tor_process = stem.process.launch_tor_with_config(
            tor_cmd=runner.get_tor_command(),
            config={"SocksPort": "2777", "ControlPort": "2778", "DataDirectory": self.data_directory},
            completion_percent=5,
        )

        control_socket = None
        try:
            control_socket = stem.socket.ControlPort(port=2778)
            stem.connection.authenticate(control_socket, chroot_path=runner.get_chroot())

            # exercises the socket
            control_socket.send("GETCONF ControlPort")
            getconf_response = control_socket.recv()
            self.assertEquals("ControlPort=2778", str(getconf_response))
        finally:
            if control_socket:
                control_socket.close()

            tor_process.kill()
            tor_process.communicate()

  def test_authenticate_general_example(self):
    """
    Tests the authenticate function with something like its pydoc example.
    """

    runner = test.runner.get_runner()
    tor_options = runner.get_options()

    try:
      control_socket = stem.socket.ControlPort(port = test.runner.CONTROL_PORT)
    except stem.SocketError:
      # assert that we didn't have a socket to connect to
      self.assertFalse(test.runner.Torrc.PORT in tor_options)
      return

    try:
      # this authenticate call should work for everything but password-only auth
      stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot())
      test.runner.exercise_controller(self, control_socket)
    except stem.connection.IncorrectSocketType:
      self.fail()
    except stem.connection.MissingPassword:
      self.assertTrue(test.runner.Torrc.PASSWORD in tor_options)
      controller_password = test.runner.CONTROL_PASSWORD

      try:
        stem.connection.authenticate_password(control_socket, controller_password)
        test.runner.exercise_controller(self, control_socket)
      except stem.connection.PasswordAuthFailed:
        self.fail()
    except stem.connection.AuthenticationFailure:
      self.fail()
    finally:
      control_socket.close()

 def test_launch_tor_with_config(self):
   """
   Exercises launch_tor_with_config.
   """
   
   test.runner.only_run_once(self, "test_launch_tor_with_config")
   
   # Launch tor without a torrc, but with a control port. Confirms that this
   # works by checking that we're still able to access the new instance.
   
   tor_process = stem.process.launch_tor_with_config(
     config = {'SocksPort': '2777', 'ControlPort': '2778'},
     completion_percent = 5
   )
   
   control_socket = None
   try:
     control_socket = stem.socket.ControlPort(control_port = 2778)
     runner = test.runner.get_runner()
     stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot())
     
     # exercises the socket
     control_socket.send("GETCONF ControlPort")
     getconf_response = control_socket.recv()
     self.assertEquals("ControlPort=2778", str(getconf_response))
   finally:
     if control_socket: control_socket.close()
     tor_process.kill()

  def test_launch_tor_with_config_via_stdin(self):
    """
    Exercises launch_tor_with_config when we provide our torrc via stdin.
    """

    runner = test.runner.get_runner()
    tor_process = stem.process.launch_tor_with_config(
      tor_cmd = runner.get_tor_command(),
      config = {
        'SocksPort': '2777',
        'ControlPort': '2778',
        'DataDirectory': self.data_directory,
      },
      completion_percent = 5
    )

    control_socket = None
    try:
      control_socket = stem.socket.ControlPort(port = 2778)
      stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot())

      # exercises the socket
      control_socket.send('GETCONF ControlPort')
      getconf_response = control_socket.recv()
      self.assertEqual('ControlPort=2778', str(getconf_response))
    finally:
      if control_socket:
        control_socket.close()

      tor_process.kill()
      tor_process.wait()

  def test_launch_tor_with_config_via_file(self):
    """
    Exercises launch_tor_with_config when we write a torrc to disk.
    """

    # Launch tor without a torrc, but with a control port. Confirms that this
    # works by checking that we're still able to access the new instance.

    runner = test.runner.get_runner()
    tor_process = stem.process.launch_tor_with_config(
      tor_cmd = runner.get_tor_command(),
      config = {
        'SocksPort': '2777',
        'ControlPort': '2778',
        'DataDirectory': self.data_directory,
      },
      completion_percent = 5
    )

    control_socket = None
    try:
      control_socket = stem.socket.ControlPort(port = 2778)
      stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot())

      # exercises the socket
      control_socket.send('GETCONF ControlPort')
      getconf_response = control_socket.recv()
      self.assertEqual('ControlPort=2778', str(getconf_response))
    finally:
      if control_socket:
        control_socket.close()

      tor_process.kill()
      tor_process.wait()

 def test_authenticate_general_controller(self):
   """
   Tests that the authenticate function can authenticate via a Controller.
   """
   
   runner = test.runner.get_runner()
   with runner.get_tor_controller(False) as controller:
     stem.connection.authenticate(controller, test.runner.CONTROL_PASSWORD, runner.get_chroot())
     test.runner.exercise_controller(self, controller)

 def test_authenticate_general_socket(self):
   """
   Tests that the authenticate function can authenticate to our socket.
   """
   
   if test.runner.require_control(self): return
   
   runner = test.runner.get_runner()
   with runner.get_tor_socket(False) as control_socket:
     stem.connection.authenticate(control_socket, test.runner.CONTROL_PASSWORD, runner.get_chroot())
     test.runner.exercise_controller(self, control_socket)

  def test_connect(self):
    """
    Basic sanity checks for the connect function.
    """

    runner = test.runner.get_runner()

    control_socket = stem.connection.connect(
      control_port = ('127.0.0.1', test.runner.CONTROL_PORT),
      control_socket = test.runner.CONTROL_SOCKET_PATH,
      password = test.runner.CONTROL_PASSWORD,
      chroot_path = runner.get_chroot(),
      controller = None)

    test.runner.exercise_controller(self, control_socket)

 def test_connect_socket_file(self):
   """
   Basic sanity checks for the connect_socket_file function.
   """
   
   runner = test.runner.get_runner()
   
   control_socket = stem.connection.connect_socket_file(
     socket_path = test.runner.CONTROL_SOCKET_PATH,
     password = test.runner.CONTROL_PASSWORD,
     chroot_path = runner.get_chroot(),
     controller = None)
   
   if test.runner.Torrc.SOCKET in runner.get_options():
     test.runner.exercise_controller(self, control_socket)
     control_socket.close()
   else:
     self.assertEquals(control_socket, None)

 def test_launch_tor_with_config(self):
   """
   Exercises launch_tor_with_config.
   """
   
   if not stem.prereq.is_python_26() and stem.util.system.is_windows():
     test.runner.skip(self, "(unable to kill subprocesses)")
     return
   
   if test.runner.only_run_once(self, "test_launch_tor_with_config"): return
   
   # Launch tor without a torrc, but with a control port. Confirms that this
   # works by checking that we're still able to access the new instance.
   
   runner = test.runner.get_runner()
   tor_process = stem.process.launch_tor_with_config(
     tor_cmd = runner.get_tor_command(),
     config = {'SocksPort': '2777', 'ControlPort': '2778'},
     completion_percent = 5
   )
   
   control_socket = None
   try:
     control_socket = stem.socket.ControlPort(control_port = 2778)
     stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot())
     
     # exercises the socket
     control_socket.send("GETCONF ControlPort")
     getconf_response = control_socket.recv()
     self.assertEquals("ControlPort=2778", str(getconf_response))
   finally:
     if control_socket: control_socket.close()
     
     if stem.prereq.is_python_26():
       tor_process.kill()
     elif not stem.util.system.is_windows():
       os.kill(tor_process.pid, signal.SIGTERM)
       
       # On OSX, python 2.5 this kill call doesn't seem to block, causing our
       # tor instance to linger and cause a port conflict with the following
       # test. Giving it a moment to kill for realz.
       
       time.sleep(0.5)

 def test_connect_port(self):
   """
   Basic sanity checks for the connect_port function.
   """
   
   if test.runner.require_control(self): return
   
   runner = test.runner.get_runner()
   
   control_socket = stem.connection.connect_port(
     control_port = test.runner.CONTROL_PORT,
     password = test.runner.CONTROL_PASSWORD,
     chroot_path = runner.get_chroot(),
     controller = None)
   
   if test.runner.Torrc.PORT in runner.get_options():
     test.runner.exercise_controller(self, control_socket)
     control_socket.close()
   else:
     self.assertEquals(control_socket, None)

  def test_launch_tor_with_config(self):
    """
    Exercises launch_tor_with_config.
    """

    if not stem.prereq.is_python_26() and stem.util.system.is_windows():
      test.runner.skip(self, "(unable to kill subprocesses)")
      return

    if test.runner.only_run_once(self, "test_launch_tor_with_config"):
      return

    # Launch tor without a torrc, but with a control port. Confirms that this
    # works by checking that we're still able to access the new instance.

    runner = test.runner.get_runner()
    tor_process = stem.process.launch_tor_with_config(
      tor_cmd = runner.get_tor_command(),
      config = {
        'SocksPort': '2777',
        'ControlPort': '2778',
        'DataDirectory': self.data_directory,
      },
      completion_percent = 5
    )

    control_socket = None
    try:
      control_socket = stem.socket.ControlPort(port = 2778)
      stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot())

      # exercises the socket
      control_socket.send("GETCONF ControlPort")
      getconf_response = control_socket.recv()
      self.assertEquals("ControlPort=2778", str(getconf_response))
    finally:
      if control_socket:
        control_socket.close()

      _kill_process(tor_process)