Include file resolution
This is a section you should hopefully never need to read. It explains in detail how implicit Procedure and Component references are resolved during test replay. If you need to read it, your test suite include hierarchy probably is too complicated and you should consider simplifying your includes.
There are basically two scenarios in which QF-Test must implicitly resolve a Procedure or Component reference to another suite when the requested Procedure or Component cannot be found in the current (or explicitly referenced) suite:
- The current suite includes other suites (by defining them in the Include files attribute of the Test suite root node). In this case, QF-Test searches all included suites in the given order.
- The current suite (or rather one of its Procedures) was called by another suite. Here QF-Test searches the calling suite for the requested node.
The whole thing gets complicated, when (possibly indirect) Procedure calls across test suite boundaries and (possibly indirect, maybe even recursive) includes are combined. Following are detailed explanations of the search algorithm that will hopefully enable you to debug and resolve any include-file related problems.
- Whenever execution leaves the current suite to continue with some Procedure or to retrieve a Component, the other suite becomes the current suite. This process is complemented by two things: the old suite is pushed onto the so-called call-stack and the variable bindings of the new current suite are pushed on top of the fallback bindings stack (see chapter 6), so they override the bindings of the old suite. In the run log this process is documented by adding a Suite-change node which holds all of the run log nodes for the execution that takes place outside the old suite.
- Any search through test suites starts with the current suite, then continues top-down through the call-stack. So if, for example, A calls B which calls C, then C is searched first, followed by B and finally A.
- Includes are considered stronger bindings than the call-stack. This means that during the search through the current suite and the suites on the call-stack, at each step the included test suites are searched before moving to the next suite on the call-stack. For example, if A calls B which includes C, A is on the call-stack and B is the current Suite, then B will be searched first, then C, and lastly A.
- In case of multiple, possibly indirect includes, the search is always conducted depth-first in the oder in which the include files are listed. This means that if A includes B and C, and B includes D, first A is searched, followed by B, then D and then C.
- If a Procedure is found (possibly indirectly) in an included test suite (as opposed to the current suite, an explicitly referenced suite or a suite on the call-stack), the change from the old current suite to the new current suite doesn't take place in one step. This has to be illustrated with an example right from the start or we'll get totally lost: Let's say A calls B and that A includes C. B calls a Procedure which is found in C by way of A. Instead of changing suites directly from B to C, A will first become the current suite and then C. As a consequence, A gets pushed onto the call-stack again on top of B and its variable bindings are also pushed again on top of B's bindings on the fallback bindings stack. The reasoning behind this is that C, which is now the current suite, is "closer to" A, which includes C, than it is to B, which only happened to be called by A. One could also say that inclusion creates a kind of union, so that to B, A and C will always appear as a single test suite as long as B doesn't call C explicitly.
- That's it, except for one thing: During a search QF-Test never searches a suite twice. This would be useless in any case, but it is more than an optimization, since it prevents trouble with recursive includes if A includes B and B includes A.
If you really have a problem determining how, why or why not a certain Procedure or Component was retrieved, first take a look at the run log. It shows exactly which suites were used and which variable expansions took place.