tools/tbot/README.create_a_new_testcase

   1 # Copyright (c) 2016 DENX Software Engineering GmbH
   2 # Heiko Schocher <hs@denx.de>
   3 #
   4 # SPDX-License-Identifier:      GPL-2.0+
   5 #
   6
   7 write a new testcase
   8 =====================
   9
  10 A TC is written in python, so you can use python as usual. For accessing
  11 the boards console, use functions from the tbotlib, therefore
  12
  13 First import the tbotlib with the line:
  14
  15   from tbotlib import tbot
  16
  17 If your TC uses variables, please add a line which adds them to
  18 the log file (for debugging purposes):
  19
  20   logging.info("args: %s ...", tb.varname, ...)
  21
  22 Say tbot, for which board state your TC is valid with:
  23
  24   tb.set_board_state("u-boot")
  25
  26 Then you are ready ... and you can use the tbotlib funtions
  27 for writting/reading to the boards console.
  28
  29 Big fat warning:
  30
  31 A TC must worry about to end only if a board has finished the shell
  32 command!
  33
  34 Not following this rule, will end in unpredictable behaviour.
  35
  36 (hopefully) useful tbotlib functions
  37 ====================================
  38 - set the board state, you want to test
  39   tb.set_board_state(state)
  40   states are: "u-boot" or "linux"
  41   If tbot could not set the board state, tbot ends with failure.
  42
  43 - write a command to the boards console:
  44   tb.eof_write_con(command):
  45     write the command to the boards console. If this
  46     fails, tbot ends with failure
  47
  48 - write a command to boards console and wait for prompt:
  49   tb.eof_write_cmd(fd, command):
  50     fd: filedescriptor which is used, use tb.channel_con for boards console
  51     command: command which is written to fd
  52
  53     Wait endless for board prompt
  54
  55 - write a list of commands to boards console:
  56   tb.eof_write_cmd_list(fd, cmdlist):
  57     fd: filedescriptor which is used, use tb.channel_con for boards console
  58     cmdlist: python list of commandstrings which is written to fd
  59
  60 - wait for boards prompt:
  61   tb.eof_read_end_state_con(retry):
  62     retry: deprecated, not used anymore, cleanup needed here...
  63     tbot waits endless for the boards prompt
  64
  65 - write a command, wait for prompt and check, if a string is read
  66   tb.write_cmd_check(fd, cmd, string):
  67     fd: filedescriptor which is used, use tb.channel_con for boards console
  68     cmd: command, which is send to fd
  69     string: string which should be read from fd
  70
  71     return value:
  72       True, if string is read and tbot got back boards prompt
  73       False, else
  74
  75   tb.eof_write_cmd_check(fd, cmd, string):
  76     same as tb.write_cmd_check(fd, cmd, string) except, that tbot
  77     ends immediately with Failure, if string is not read.
  78
  79 - read until prompt and search strings:
  80   tb.readline_and_search_strings(fd, strings):
  81     fd: filedescriptor which is used, use tb.channel_con for boards console
  82     strings: python list of strings, which can be read
  83       If one of this strings is read, this function return the index, which
  84       string is read. This function shoud be called in a while loop,
  85       until this function returns 'prompt'
  86
  87 - read a line from filedescriptor:
  88   not recommended to use, as the TC must check, if tprompt is read for every
  89   readen line. Also TC must ensure, that it ends only, if prompt is read.
  90   tb.read_line(fd, retry)
  91     fd: filedescriptor which is used, use tb.channel_con for boards console
  92     retry: retry of trying to reead a line
  93
  94   return values:
  95     True, if a line is read. Readen line in tb.buf[fd]
  96     False, if something read, but not a complete line
  97     None, if nothing is read
  98
  99   check if string contains prompt with:
 100   tb.is_end_fd(fd, string)
 101     fd: filedescriptor which is used, use tb.channel_con for boards console
 102     string: buffer, in which a prompt gets searched.
 103
 104 - calling other TC:
 105   eof_call_tc(name):
 106     call another TC from "src/tc"
 107     if the called TC fails with failure, tbot ends with failure
 108
 109   call_tc(name):
 110     call another TC from "src/tc"
 111     if the TC which call_tc calls  fails, call_tc() returns False, else True
 112
 113 There are more functions, but for writting TC this should be enough. But
 114 its software, so new useful functions can always pop up.
 115
 116 Heiko Schocher <hs@denx.de>
 117 v1 2016.01.23