SrcTree

SrcTree is [Sahagin intermediate data](Intermediate data format). SrcTree file name must be "srcTree".

##SrcTree definition

SrcTree YAML format is as the following:

formatVersion: <version number>
rootMethodTable:
  methods:
  - <Method definition>
  - <Method definition>
  - ...
subMethodTable:
  methods:
  - <Method definition>
  - <Method definition>
  - ...
rootClassTable:
  classes:
  - <Class definition>
  - <Class definition>
  - ...
subClassTable:
  classes:
  - <Class definition>
  - <Class definition>
  - ...
fieldTable:
  fields:
  - <Field definition>
  - <Field definition>
  - ...

key	detail
formatVersion	The format specification version number of this YAML file. Usually, this number is the same as the version number of Sahagin release the format specification change has been introduced. type: string required: Yes
rootMethodTable	In Sahagin, test method is called "root method", which means the root element of the SrcTree tree structure, and "rootMethodTable" contains all root method definitions.The definition of the test method varies with the test framework. For example, method annotated with @Test annotation is regarded as test method for JUnit4. type: single entry map (methods, Method Definition list) required: No
subMethodTable	The method which is marked as TestDoc (For example, annotated with @TestDoc annotation in Java. This depends on the implementation of the Sahagin runtime library) and not root method is called "sub method". type: single entry map (methods, Method Definition list) required: No
rootClassTable	The class or interface which has root method is called "root class". type: single entry map (classes, Class Definition list) required: No
subClassTable	The class or interface which has sub method but does not have any root method is called "sub class". type: single entry map (classes, Class Definition list) required: No
fieldTable	The field defined on root class or sub class. type: single entry map (fields, Field Definition list) required: No

If required value is "No", the entry can be omitted and the value can be null.

If a method on a superclass is overridden on the subclass of the superclass, both the overridden method and the overriding method must be included in the method table, and both the superclass and subclass must be included in the class table. If the superclass is extended but the method is not overridden, only the overriding method on subclass must be included in the method table.

Class definition

key: <class key (unique)>
qname: <qualified class name (unique)>
type: <class type>
delegateToClassKey: <class key>
testDoc: <class description>
methodKeys: <method keys>
fieldKeys: <field keys>

key	detail
key	Unique key for this class (or interface). This key is arbitrary, but must be unique in all root classes and sub classes, and a class always must have the same key value. type: string required: Yes
qname	Qualified name of this class (or interface). Qualified name has a format <dot separated package name or namespace>.<simple class name>. Package name or namespace part varies with programming language and test framework. Qualified name of the class must be unique in all root classes and sub classes. type: string required: Yes
type	"page" This class is marked as Page by @PageDoc annotation or any other marker. "class" Other. If this class is not marked but the superclass is marked, use the superclass marker as the one of this class. type: string ("page" or "class") required: No default: "class"
delegateToClassKey	TODO
testDoc	Description of this class specified by the TestDoc or PageDoc marker. If this class is not marked but the superclass is marked, use the superclass marker as the one of this class (But this behaviour is not implemented yet even on Java Sahagin runtime library. See #3). type: string required: No
methodKeys	Unique key list of the all methods defined on this class. This list does not include the methods defined on the superclass of this class. type: string list required: No
fieldKeys	TODO

Method definition

classKey: <class key>
key: <method key (unique)>
name: <not qualified method name (non-unique)>
testDoc: <method description>
capture: <capture style>
argVariables: <argument variable names>
varLengthArgIndex: <index of variable length argument>
codeBody:
  - <CodeLine definition>
  - <CodeLine definition>
  - ...

key	detail
classKey	Unique key of the class on which this method is defined. type: string required: Yes
key	Unique key for this method. This key is arbitrary, but must be unique in all root methods and sub methods, and a method always must have the same key value. type: string required: Yes
name	Non-qualified simple name of this method. This name is not unique. type: string required: Yes
testDoc	Description of this method specified by the TestDoc marker. If this method is not marked but the super method is marked, use the super method marker as the one of this method (But this behaviour is not implemented yet even on Java Sahagin runtime library. See #3). type: string required: No
capture	Screen capture setting. Screen capture is taken when sub method invocation has finished or when test has failed. Whether sub method invocation screen capture is taken depends on the setting value, but error screen capture is always taken even for "none". "thisLine" Screen capture is taken after the method invocation but not taken while stepping into the method body. "stepIn" Screen capture is taken after the method invocation and even while stepping into the method body. If you want to take screen capture recursively, specify "stepIn" for each invoked method. "none" Screen capture is not taken after the method invocation and while stepping into the method body. "stepInOnly" Screen capture is not taken after the method invacation but taken while stepping into the method body. This setting value is not useful, and you never use this value. type: string ("thisLine" or "stepIn" or "none") required: No default: "thisLine" is default. "stepIn" is not default since taking too many screen captures makes test slower.
argVariables	List of the argument variable name of this method. type: string list required: No
varLengthArgIndex	Index of the variable length argument, which some programming languages support. Only last one argument of the method can be variable length argument. Set -1 if this method does not have a variable length argument. type: integer required: No default: -1
codeBody	List of the method body code lines. Source code comment is not included. type: CodeLine list required: No

Methods in SrcTree always must be linked to some Class, and even if target programming language or test framework does not have the concept of the class, some pseudo class definition must be required according to the namespace or the directory hierarchy. This specification is mainly for the interoperability with Jenkins JUnit output XML format.

Field definition

classKey: <class key>
key: <field key (unique)>
name: <not qualified field name (non-unique)>
testDoc: <field description>

key	detail
classKey	Unique key of the class on which this field is defined. type: string required: Yes
key	Unique key for this field. This key is arbitrary, but must be unique in all fields, and a field always must have the same key value. type: string required: Yes
name	Non-qualified simple name of this field. This name is not unique. type: string required: Yes
testDoc	Description of this field specified by the TestDoc marker. type: string required: No

Like [Method definition](#Method definition), field in SrcTree always must be linked to some Class, and even if target programming language or test framework does not have the concept of the class, some pseudo class definition must be required according to the namespace or the directory hierarchy.

CodeLine definition

Each code line for single statement.

startLine: <code start line number>
endLine: <code end line number>
code: <Code definition>

key	detail
startLine	Star source code line number of this code line. This number starts with 1. type: integer required: Yes
endLine	End source code line number of this code line. If a statement is multi-line statement, the CodeLine for the statement is single CodeLine, and the startLine and the endLine are different. type: integer required: Yes
code	The actual content of this code line. type: Code required: Yes

Code definition

original: <original source code>
type: <code line type>

key	detail
original	Original source code. type: string required: Yes
type	"string" String literal such as "ABC". "method" Invocation of sub method. "arg" Reference to the argument of the method this code body belongs to. "varAssign" Value assignment to the local variable or field. If a local variable is declared but not assigned initial value on the same line, the code is not regarded as "varAssign". "localVar" Reference to the local variable. "field" Reference to the field. "classInstance" Reference to the class itself. "step" Group of some code lines. This is mainly used to represent step definition of each step in BDD framework such as Cucumber, and can be used only in the method code body top level code line (But this behaviour is not implemented yet even on Java Sahagin runtime library. #14). "stepLabel" Another representation of code line group. "stepLabel" Codes can be used only in the method code body top level code line, and code lines in the method code body between "stepLabel" Code and the next "stepLabel" Code are grouped as one group. Code line group concept can be represented by any of "step" or "stepLabel", and you can choose the one which makes it easy to generate srcTree from the test code according to the test framework or programming language. "unknown" Other. type: string (one of "string", "method", "arg", "varAssign", "localVar" , "field", "classInstance", "step", "stepLabel", "unknown") required: Yes

"string" type Code additional definition

If type of Code definition is "string", the definition has the following entries in addition to the standard Code definition entries.

value: <string value>

key	detail
value	The string value this string literal represents. type: string required: Yes

"method" type Code additional definition

If type of Code definition is "method", the definition has the following entries in addition to the standard Code definition entries.

methodKey: <method key>
args:
- <Code definition>
- <Code definition>
- ...
thisInstance: <Code definition>
childInvoke: <child invocation flag>

key	detail
methodKey	Unique key of the invoked sub method. type: string required: Yes
args	Code definition list of the argument of this method invocation. type: Code list required: No
thisInstance	Code definition of the instance which qualifies this method invocation. If this method is static method and qualified by the class name, "thisInstance" represents "classInstance" type Code. If this method is not qualified by any instance or class name, "thisInstance" value is null. type: Code required: No
childInvoke	If true is specified, this code represents not an invocation of sub method but an invocation of non sub method inherited from the sub method for the methodKey. type: boolean required: No default: false

"arg" type Code additional definition

If type of Code definition is "arg", the definition has the following entries in addition to the standard Code definition entries.

argIndex: <method argument index>

key	detail
argIndex	Index of the method argument this Code definition represents. The index number starts with 0. type: integer required: Yes

"varAssign" type Code additional definition

If type of Code definition is "varAssign", the definition has the following entries in addition to the standard Code definition entries.

variable: <Code definition>
value: <Code definition>

key	detail
variable	"localVar" or "field" code. type: Code required: Yes
value	Value assigned to this local variable or field. type: Code required: Yes

"localVar" type Code additional definition

If type of Code definition is "localVar", the definition has the following entries in addition to the standard Code definition entries.

name: <local variable name>

key	detail
name	Local variable name. type: string required: Yes

"field" type Code additional definition

If type of Code definition is "field", the definition has the following entries in addition to the standard Code definition entries.

fieldKey: <field key>
thisInstance: <Code definition>

key	detail
fieldKey	Unique key of the field this code refers to. type: string required: Yes
thisInstance	Code definition of the instance which qualified this field reference. If this field is static field and qualified by the class name, "thisInstance" represents "classInstance" type Code. If this field is not qualified by any instance or class name, "thisInstance" value is null. type: Code required: No

"classInstance" type Code additional definition

If type of Code definition is "classInstance", the definition has the following entries in addition to the standard Code definition entries.

classKey: <class key>

key	detail
classKey	Unique key of the class this code refers to. type: string required: Yes

"step" type Code additional definition

If type of Code definition is "step", the definition has the following entries in addition to the standard Code definition entries.

label: <label text>
text: <step description>
stepBody:
  - <CodeLine definition>
  - <CodeLine definition>
  - ...

key	detail
label	Types of this step. This is mainly used to represent BDD step type such as "Given", "When", "Then". type: string required: Yes
text	Description of this step. type: string required: Yes
stepBody	List of the code lines in this step group. Source code comment is not included. type: CodeLine list required: No

"stepLabel" type Code additional definition

If type of Code definition is "stepLabel", the definition has the following entries in addition to the standard Code definition entries.

label: <label text>
text: <step description>

key	detail
label	Types of this step. This is mainly used to represent BDD step type such as "Given", "When", "Then". type: string required: Yes
text	Description of this step. type: string required: Yes