expect-lite as a Library
Author: Craig Miller
Description: Automation for the rest of us
Keywords: test testing automation expec-lite script expect project google

# expect-lite ## Automation for the rest of us now in Library form |  |  | ## Using expect-lite as a TCL Library expect-lite can now can run in two modes: standalone, and library-mode. In library-mode expect-lite be used within a TCL (Tool Command Language) program. What this means is that expect-lite can be called programmatically from TCL, allowing the integration of the ease of expect-lite scripting with a more complex TCL-based regression system. An example TCL program, test_el_lib.tcl, using library-mode is included in the tarball. In keeping with the principle of 'keeping it simple', the goal is allow expect-lite scripts to be used unchanged, or with minimal changes, in a native TCL environment. Important differences from standalone mode are described below. The expect-lite library seeks to leverage the ease of expect-lite scripting with easy integration into a more complex TCL environment. ## Applications Programmers Interface (API) As part of playing well with other TCL software, a majority of expect-lite has been encapsulated in a TCL namespace, expectlite (TCL does not permit dash in a namespace name). This prevents procedure- (or functions) and variable-name collisions with other TCL code. The API includes the following functions, listed in typical order of use: expectlite::_el_init_library expectlite::_el_import_session_ids expectlite::_el_import_const expectlite::_el_buffer expectlite::_el_exec_script ## Details & examples of the API Included in the expect-lite tarball is the file test_el_lib.tcl. The example program, is a hybrid script, part TCL, and part expect-lite. The API functions are listed below in more detail, and are listed without the namespace name: expectlite for brevity. ### _el_init_library Used to initialize the expect-lite library, loads the expect library, and optionally can take a list of expect-lite constants (read-only variables) as name value pairs in the form of var=value, and expect-lite directives. Example:
    _el_init_library "*EXP_INFO IP=10.5.5.5 *DEBUG"
### _el_import_session_ids The TCL program may have previously created expect sessions which would be used in the expect-lite script. Session names are imported into the expect-lite *FORK sessions, and the expect-lite script will have access to use the session names defined by the program. Since TCL can not pass arrays, the array of sessions is passed as a list (via [array get session]). Example:
    # create spawn sessions and set prompt to identify the session
    spawn bash
    send "export PS1='0\$ '\n"
    set session(default) $spawn_id

    spawn bash
    send "export PS1='1\$ '\n"
    set session(dut1) $spawn_id

    _el_import_session_ids [array get session]
### _el_import_const As mentioned earlier, it is possible to pass expect-lite constants and directives via _el_init_library call. However that can only be called once. It may be more desirable to create a loop where TCL variables are imported into expect-lite. The _el_import_const function that does this can be called many times. Example:
    _el_import_const "DUT=mydut *NOFAIL"

    _el_import_const "DUT2=thatdut "
### _el_buffer This function is used to read a file into expect-lite's private command buffer space. In the included example test_el_lib.tcl, the TCL file itself is read into _el_buffer. Since any line that does not begin with expect-lite's punctuation characters is ignored, all the TCL in the test program will be ignored. This function returns a pointer to the private buffer space. This must be passed to _el_exec_script for execution. Example:
    # read this file as expect-lite script, and return pointer to buffer
    set cmd_file $argv0
    set cmd_list_ptr [_el_buffer $cmd_file]
### _el_exec_script Having prepared the library with the necessary information, this function is the core of expect-lite. It interprets the expect-lite punctuation commands (such as '>', '<'), as well as dereference expect-lite variables. This function returns the following result codes: zero (0) if the expect-lite script passes one (1) if the expect-lite script fails two (2) if the result is unknown (usually abnormal end of the script). Example:
    # call el script exec
    set RESULT [ _el_script_exec "" $cmd_list_ptr ]

    # Print result of test
    switch $RESULT {
    	0 	{ puts "\nTest Passed" }
    	1	{ puts "\nTest Failed" }
    	2	{ puts "\nTest Abend" }
    }
## Changes in behaviour when running expect-lite as a library The thinking is that when running expect-lite as a Library (aka library mode), one would not be debugging the expect-lite script itself, but rather one's focused on the integration of the program into the TCL environment. Therefore the following functionality is changed compared to how expect-lite runs in standalone mode. *INTERACT is be ignored in library mode *TCL is a method which is ignored during normal expect-lite operation, but in library mode, it enables the calling of native TCL functions from within the embedded expect-lite script. Notes: *TCL is still line oriented, and should only be used for one line TCL commands, or calls to TCL functions *TCL has no protection, bad TCL syntax will crash the TCL program expect-lite timeouts (@number) will not occur on a *TCL line ~include_file is no longer ignored in Library mode (as of v4.6.2). Use *NOINCLUDE to retain v4.1.0 behaviour

19 November 2013
http://expect-lite.sourceforge.net/
this document for version 4.6.2 and above