2WօdZddlZddlZddlZddlZddlZddlZddlZddlZddl Z ddl m Z ddl m Z ejeZeZdZej(fdZdZdefd Zd Zd Zd ZGd deZGddeZGddeZGddeZ GddeZ!Gdde e!Z"Gdde e!Z#Gdde#Z$GddeZ%Gdd e Z&Gd!d"e jNZ'y)#a Utility classes and functions that make it easy to write :mod:`unittest` compatible test suites. Over the years I've developed the habit of writing test suites for Python projects using the :mod:`unittest` module. During those years I've come to know :pypi:`pytest` and in fact I use :pypi:`pytest` to run my test suites (due to its much better error reporting) but I've yet to publish a test suite that *requires* :pypi:`pytest`. I have several reasons for doing so: - It's nice to keep my test suites as simple and accessible as possible and not requiring a specific test runner is part of that attitude. - Whereas :mod:`unittest` is quite explicit, :pypi:`pytest` contains a lot of magic, which kind of contradicts the Python mantra "explicit is better than implicit" (IMHO). N)StringIO) random_string)CallableTimedOut CaptureBuffer CaptureOutputContextManagerCustomSearchPath MockedProgramPatchedAttribute PatchedItemTemporaryDirectoryTestCaseconfigure_logging make_dirsretryrun_cli skip_on_raisetouchc ddl}|j|y#t$rtj|ddYywxYw)aconfigure_logging(log_level=logging.DEBUG) Automatically configure logging to the terminal. :param log_level: The log verbosity (a number, defaults to :mod:`logging.DEBUG `). When :mod:`coloredlogs` is installed :func:`coloredlogs.install()` will be used to configure logging to the terminal. When this fails with an :exc:`~exceptions.ImportError` then :func:`logging.basicConfig()` is used as a fall back. rN)levelz;%(asctime)s %(name)s[%(process)d] %(levelname)s %(message)sz%Y-%m-%d %H:%M:%S)rformatdatefmt) coloredlogsinstall ImportErrorlogging basicConfig) log_levelrs :/usr/lib/python3.12/site-packages/humanfriendly/testing.pyrrBsA)), )P' ))s !==cntjj|stj|yy)zc Create missing directories. :param pathname: The pathname of a directory (a string). N)ospathisdirmakedirs)pathnames rrrXs% 77== " H #<cd}|tjz } |}|dur|S tj|kDr ttj||dkr|dz}P#|$rtj|kDrY?wxYw)aretry(func, timeout=60, exc_type=AssertionError) Retry a function until assertions no longer fail. :param func: A callable. When the callable returns :data:`False` it will also be retried. :param timeout: The number of seconds after which to abort (a number, defaults to 60). :param exc_type: The type of exceptions to retry (defaults to :exc:`~exceptions.AssertionError`). :returns: The value returned by `func`. :raises: Once the timeout has expired :func:`retry()` will raise the previously retried assertion error. When `func` keeps returning :data:`False` until `timeout` expires :exc:`CallableTimedOut` will be raised. This function sleeps between retries to avoid claiming CPU cycles we don't need. It starts by sleeping for 0.1 second but adjusts this to one second as the number of retries grows. g?F)timersleep)functimeoutexc_typepauseresults rrrbs( E tyy{G  )VFU" # yy{W$&(( 5 19 QJE   yy{W$% s A++B  B cFt|}|jd|jdtjt j d|d}d}d} ttd|5|jdd|d<tdi|5} ||jj}|jj}t ddddddt j d |j%dd}d|fg} d|fd|fg} |r| n| } | D]5\} } | rt j d| |  t j d| 7||fS#|jj}|jj}twxYw#1swYxYw#1swYxYw#t$ra}t|tr-t j d |j |j }nt j#d d d }Yd}~#d}~wwxYw)a Test a command line entry point. :param entry_point: The function that implements the command line interface (a callable). :param arguments: Any positional arguments (strings) become the command line arguments (:data:`sys.argv` items 1-N). :param options: The following keyword arguments are supported: **capture** Whether to use :class:`CaptureOutput`. Defaults to :data:`True` but can be disabled by passing :data:`False` instead. **input** Refer to :class:`CaptureOutput`. **merged** Refer to :class:`CaptureOutput`. **program_name** Used to set :data:`sys.argv` item 0. :returns: A tuple with two values: 1. The return code (an integer). 2. The captured output (a string). r program_namez3Calling command line entry point with arguments: %sNargvcaptureTenabledz/Command line entry point returned successfully!z6Intercepting return code %s from SystemExit exception.z4Defaulting return code to 1 due to raised exception.exc_infor)mergedFzmerged streamsstdoutstderrzOutput on %s: %szNo output on %s.)listinsertpopsys executableloggerdebugr rr:getvaluer;r BaseException isinstance SystemExitcodewarningget) entry_point argumentsoptions returncoder:r;capturere is_mergedmerged_streamsseparate_streamsstreamsnamevalues rrrs4YI Q NCNNCD LLF RJ F FH c69 5!(Y!=GI ))X (M&__557F%__557F&'*6.  FG He,I'01N!6*Xv,>? )n/?G e  LL,dE : LL+T 2  v 5&__557F%__557F&'*)6 5  a $ LLQSTSYSY ZJ NNQ\`N aJ sbF6*!F* F E>FF*F6AFFF' #F**F3/F66 H ?AHH cfd}|S)a; Decorate a test function to translation specific exception types to :exc:`unittest.SkipTest`. :param exc_types: One or more positional arguments give the exception types to be translated to :exc:`unittest.SkipTest`. :returns: A decorator function specialized to `exc_types`. cFtjfd}|S)Nc |i|S#$r=}tjddtjdt |zd}~wwxYw)Nz-Translating exception to unittest.SkipTest ..Tr7z#skipping test because %s was raised)rBrCunittestSkipTesttype)argskwrP exc_typesfunctions rwrapperz1skip_on_raise..decorator..wrappers[ Y,,, Y LW[ \''(MPTUVPW(WXX Ys A 8AA ) functoolswraps)r`rar_s` r decoratorz skip_on_raise..decorators'  " Y # Y r&r<)r_rds` rrrs r&cttjj|t |d5tj |ddddy#1swYyxYw)z The equivalent of the UNIX :man:`touch` program in Python. :param filename: The pathname of the file to touch (a string). Note that missing directories are automatically created using :func:`make_dirs()`. aN)rr!r"dirnameopenutime)filenames rrrs=bggooh'( h  4    s AAceZdZdZy)rz3Raised by :func:`retry()` when the timeout expires.N)__name__ __module__ __qualname____doc__r<r&rrrs=r&rceZdZdZdZddZy)rz5Base class to enable composition of context managers.c|S)Enable use as context managers.r<selfs r __enter__zContextManager.__enter__s r&Ncy)rrNr<)rtr/ exc_value tracebacks r__exit__zContextManager.__exit__sr&NNN)rlrmrnroruryr<r&rrrs?.r&rc4eZdZdZdZfdZdfd ZxZS)r zTContext manager that temporary replaces an object attribute using :func:`setattr()`.cD||_||_||_t|_y)z Initialize a :class:`PatchedAttribute` object. :param obj: The object to patch. :param name: An attribute name. :param value: The value to set. N)object_to_patchattribute_to_patch patched_valueNOTHINGoriginal_value)rtobjrUrVs r__init__zPatchedAttribute.__init__ s$ #"&"%r&ctt| t|j|j t |_t|j|j |j|jS)zk Replace (patch) the attribute. :returns: The object whose attribute was patched. ) superr rugetattrr}r~rrsetattrrrt __class__s rruzPatchedAttribute.__enter__s[ /1%d&:&:DCleanup the temporary directory using :func:`shutil.rmtree()`.N)rr ryrshutilrmtreers rryzTemporaryDirectory.__exit__sD  $09iP  # # / MM$22 3'+D $ 0r&rzrrs@rr r ]s ( (,,r&r c0eZdZdZdZdZdfd ZxZS)MockedHomeDirectoryz Context manager to temporarily change ``$HOME`` (the current user's profile directory). This class is a composition of the :class:`PatchedItem` and :class:`TemporaryDirectory` context managers. ctj|tjdtjj dt j|y)z1Initialize a :class:`MockedHomeDirectory` object.HOMEN)r rr!environrJr rss rrzMockedHomeDirectory.__init__s5T2::vrzz~~f7MN##D)r&chtj|}||_tj||Sz Activate the custom ``$PATH``. :returns: The pathname of the directory that has been added to ``$PATH`` (a string). )r rurr rt directorys rruzMockedHomeDirectory.__enter__s2'006 'd#r&c0tt| |||y)z Deactivate the custom ``$HOME``.N)rrryrs rryzMockedHomeDirectory.__exit__s !41(IyQr&rzrrs@rrrs* "RRr&rcBeZdZdZddZdZdfd ZedZxZ S)r z Context manager to temporarily customize ``$PATH`` (the executable search path). This class is a composition of the :class:`PatchedItem` and :class:`TemporaryDirectory` context managers. c||_tj|tjd|j t j|y)a  Initialize a :class:`CustomSearchPath` object. :param isolated: :data:`True` to clear the original search path, :data:`False` to add the temporary directory to the start of the search path. PATHN)isolated_search_pathr rr!rcurrent_search_pathr )rtisolateds rrzCustomSearchPath.__init__s8%-!T2::vt7O7OP##D)r&ctj|}|jr|nItjj |g|j jtjz|_tj||Sr) r rurr!pathsepjoinrsplitrr rs rruzCustomSearchPath.__enter__sm'006 22I)t/G/G/M/Mbjj/Y!YZ  d#r&c0tt| |||y)z Deactivate the custom ``$PATH``.N)rr ryrs rryzCustomSearchPath.__exit__s .xINr&c^tjjdtjS)z8The value of ``$PATH`` or :data:`os.defpath` (a string).r)r!rrJdefpathrss rrz$CustomSearchPath.current_search_pathszz~~fbjj11r&)Frz) rlrmrnrorrurypropertyrrrs@rr r s, **O22r&r c8eZdZdZdfd ZfdZfdZxZS)r z Context manager to mock the existence of a program (executable). This class extends the functionality of :class:`CustomSearchPath`. cb||_||_||_d|_tt |y)a Initialize a :class:`MockedProgram` object. :param name: The name of the program (a string). :param returncode: The return code that the program should emit (a number, defaults to zero). :param script: Shell script code to include in the mocked program (a string or :data:`None`). This can be used to mock a program that is expected to generate specific output. N)r3program_returncodeprogram_scriptprogram_signal_filerr r)rtrUrNscriptrs rrzMockedProgram.__init__s2!",$#'  mT+-r&ctt| }tjj |dt dz|_tjj ||j}t|d5}|jd|jdtj|jz|jr,|jd|jjz|jd|jzdddtj |d |S#1swY!xYw) z Create the mock program. :returns: The pathname of the directory that has been added to ``$PATH`` (a string). zprogram-was-run-%s wz #!/bin/sh z echo > %s z%s zexit %i Ni)rr rur!r"rrrr3rhwritepipesquoterstriprchmod)rtrr%handlers rruzMockedProgram.__enter__s-8: #%77<< ;OR_`bRc;c#d 77<< 4+<+<= (C F LL ' LLT5M5M)NN O"" Vd&9&9&?&?&AAB LLt'>'>> ? ! 5!! s ;BD44D=c |jr)tjj|jsJd|jz t t ||i|S#t t ||i|ccYSxYw)z Ensure that the mock program was run. :raises: :exc:`~exceptions.AssertionError` when the mock program hasn't been run. zIt looks like %r was never run!)rr!r"isfiler3rr ryrtr]r^rs rryzMockedProgram.__exit__sx D++t?W?W0X H2T5F5FF HX0X6CC C56CC Cs A A A8)rNrrs@rr r s .&& D Dr&r cHeZdZdZddZfdZd fd ZdZdZdZ xZ S) ra Context manager that captures what's written to :data:`sys.stdout` and :data:`sys.stderr`. .. attribute:: stdin The :class:`~humanfriendly.compat.StringIO` object used to feed the standard input stream. .. attribute:: stdout The :class:`CaptureBuffer` object used to capture the standard output stream. .. attribute:: stderr The :class:`CaptureBuffer` object used to capture the standard error stream. ct|_t_|r jn t_g_|r%j j fddDyy)a Initialize a :class:`CaptureOutput` object. :param merged: :data:`True` to merge the streams, :data:`False` to capture them separately. :param input: The data that reads from :data:`sys.stdin` should return (a string). :param enabled: :data:`True` to enable capturing (the default), :data:`False` otherwise. This makes it easy to unconditionally use :class:`CaptureOutput` in a :keyword:`with` block while preserving the choice to opt out of capturing output. c 3TK|]}tt|t|!yw)N)r r@r).0rUrts r z)CaptureOutput.__init__..Fs)+9D!dGD$,?@9s%()stdinr:r;N)rrrr:r;patched_attributesextend)rtr9inputr6s` rrzCaptureOutput.__init__3s[e_ #o %+dkk "$   # # * *+9+  r&cntt| |jD]}|j|S)zLStart capturing what's written to :data:`sys.stdout` and :data:`sys.stderr`.)rrrur)rtcontextrs rruzCaptureOutput.__enter__Ks1 mT,...G    / r&cxtt| ||||jD]}|j|||y)zKStop capturing what's written to :data:`sys.stdout` and :data:`sys.stderr`.N)rrryr)rtr/rwrxrrs rryzCaptureOutput.__exit__Rs8 mT+HiK..G   Xy) </r&c>|jjS)z=Get the contents of :attr:`stdout` split into separate lines.get_text splitlinesrss r get_lineszCaptureOutput.get_linesX}}))++r&c6|jjS)z7Get the contents of :attr:`stdout` as a Unicode string.)r:rrss rrzCaptureOutput.get_text\{{##%%r&c6|jjS)z+Get the text written to :data:`sys.stdout`.)r:rDrss rrDzCaptureOutput.getvalue`rr&)FTrz) rlrmrnrorruryrrrDrrs@rrr!s& 0= ,&&r&rceZdZdZdZdZy)raV Helper for :class:`CaptureOutput` to provide an easy to use API. The two methods defined by this subclass were specifically chosen to match the names of the methods provided by my :pypi:`capturer` package which serves a similar role as :class:`CaptureOutput` but knows how to simulate an interactive terminal (tty). c>|jjS)z9Get the contents of the buffer split into separate lines.rrss rrzCaptureBuffer.get_linesprr&c"|jS)z3Get the contents of the buffer as a Unicode string.)rDrss rrzCaptureBuffer.get_textts}}r&N)rlrmrnrorrr<r&rrres,r&rc@eZdZdZfdZej fdZxZS)rz_Subclass of :class:`unittest.TestCase` with automatic logging and other miscellaneous features.c,tt| |i|y)z Initialize a :class:`TestCase` object. Any positional and/or keyword arguments are passed on to the initializer of the superclass. N)rrrrs rrzTestCase.__init__}s h&33r&cXt|tjjdy)asetUp(log_level=logging.DEBUG) Automatically configure logging to the terminal. :param log_level: Refer to :func:`configure_logging()`. The :func:`setUp()` method is automatically called by :class:`unittest.TestCase` before each test method starts. It does two things: - Logging to the terminal is configured using :func:`configure_logging()`. - Before the test method starts a newline is emitted, to separate the name of the test method (which will be printed to the terminal by :mod:`unittest` or :pypi:`pytest`) from the first line of logging output that the test method is likely going to generate.  N)rr@r;r)rtrs rsetUpzTestCase.setUps & )$ r&) rlrmrnrorrDEBUGrrrs@rrrysi4&mmr&r)(rorbrr!rrr@rr+rZhumanfriendly.compatrhumanfriendly.textr getLoggerrlrBobjectr__all__rrrAssertionErrorrrrr Exceptionrrr r r rr r rrrr<r&rrs&$  *,   8 $ ( (!( ),^#LJZ( !>y> .V .&X~&XR)K.)KX+,+,\!R+'9!RH32{$632l9D$9DxA&NA&HH($x  $r&