import HEAD into svn+ssh://svn.samba.org/home/svn/samba/trunk
[metze/old/v3-2-winbind-ndr.git] / source / stf / notes.txt
1                 -*- indented-text -*-
2
3 (set lotus no)
4
5
6
7 Notes on using comfychair with Samba (samba testing framework units):
8
9 The tests need to rely on some external resources, such as 
10
11 If suitable resources are not available, need to skip particular
12 tests.  Must include a message indicating what resources would be
13 needed to run that test.  (e.g. must be root.)
14
15 We want to be able to select and run particular subsets of tests, such
16 as "all winbind tests".
17
18 We want to keep the number of configurable parameters down as much as
19 possible, to make it easy on people running the tests.
20
21 Wherever possible, the tests should set up their preconditions, but a
22 few basic resources need to be provided by the people running the
23 tests.  So for example, rather than asking the user for the name of a
24 non-root user, we should give the tests the administrator name and
25 password, and it can create a new user to use.
26
27 This makes it simpler to get the tests running, and possible also
28 makes them more reproducible.
29
30 In the future, rather than using NT machines provided by the test
31 person, we might have a way to drive VMWare non-persistent sessions,
32 to make tests even more tightly controlled.
33
34
35 Another design question is how to communicate this information to the
36 tests.  If there's a lot of settings, then it might need to be stored
37 in a configuration file.  
38
39 However, if we succeed in cutting down the number of parameters, then
40 it might be straightforward to pass the information on the command
41 line or in an environment variable.  
42
43 Environment variables are probably better because they can't be seen
44 by other users, and they are more easily passed down through an
45 invocation of "make check".
46
47
48 \f
49 Notes on Samba Testing Framework for Unittests
50 ----------------------------------------------
51
52 This is to be read after reading the notes.txt from comfychair.  I'm
53 proposing a slightly more concrete description of what's described
54 there.
55
56 The model of having tests require named resources looks useful for
57 incorporation into a framework that can be run by many people in
58 widely different environments.
59
60 Some possible environments for running the test framework in are:
61
62     - Casual downloader of Samba compiling from source and just wants
63       to run 'make check'.  May only have one Unix machine and a
64       handful of clients.
65
66     - Samba team member with access to a small number of other
67       machines or VMware sessions.
68
69     - PSA developer who may not have intimate knowledge of Samba
70       internals and is only interested in testing against the PSA.
71
72     - Non-team hacker wanting to run test suite after making small
73       hacks. 
74
75     - Build farm environment (loaner machine with no physical access
76       or root privilege).
77
78     - HP BAT.
79
80 Developers in most of these environments are also potential test case
81 authors.  It should be easy for people unfamiliar with the framework
82 to write new tests and have them work.  We should provide examples and
83 the existing tests should well written and understandable.
84
85 Different types of tests:
86
87     - Tests that check Samba internals and link against
88       libbigballofmud.so.  For example:
89
90         - Upper/lowercase string functions
91         - user_in_list() for large lists
92
93     - Tests that use the Samba Python extensions.
94
95     - Tests that execute Samba command line programs, for example
96       smbpasswd. 
97
98     - Tests that require other resources on the network such as domain
99       controllers or PSAs.
100
101     - Tests that are performed on the documentation or the source code
102       such as:
103
104         - grep for common spelling mistakes made by abartlet (-:
105         - grep for company copyright (IBM, HP)
106                          
107     - Link to other existing testing frameworks (smbtorture,
108       abartlet's bash based build farm tests)
109
110 I propose a TestResourceManager which would be instantiated by a test
111 case.  The test case would require("resourcename") as part of its
112 constructor and raise a comfychair.NotRun exception if the resource
113 was not present.  A TestResource class could be defined which could
114 read a configuration file or examine a environment variable and
115 register a resource only if some condition was satisfied.
116
117 It would be nice to be able to completely separate the PSA testing
118 from the test framework.  This would entail being able to define test
119 resources dynamically, possibly with a plugin type system.
120
121 class TestResourceManager:
122     def __init__(self, name):
123         self.resources = {}
124
125     def register(self, resource):
126         name = resource.name()
127         if self.resources.has_key(name):
128             raise "Test manager already has resource %s" % name
129         self.resources[name] = resource
130
131     def require(self, resource_name):
132         if not self.resources.has_key(resource_name):
133             raise "Test manager does not have resources %s" % resource_name
134
135 class TestResource:
136     def __init__(self, name):
137         self.name = name
138
139     def name(self):
140         return self.name
141
142 import os
143
144 trm = TestResourceManager()
145
146 if os.getuid() == 0:
147     trm.register(TestResource("root"))
148
149 A config-o-matic Python module can take a list of machines and
150 administrator%password entries and classify them by operating system
151 version and service pack.  These resources would be registered with
152 the TestResourceManager.
153
154 Some random thoughts about named resources for network servers:
155
156 require("nt4.sp3")
157 require("nt4.domaincontroller")
158 require("psa")
159
160 Some kind of format for location of passwords, libraries:
161
162 require("exec(smbpasswd)")
163 require("lib(bigballofmud)")
164
165 maybe require("exec.smbpasswd") looks nicer...
166
167 The require() function could return a dictionary of configuration
168 information or some handle to fetch dynamic information on.  We may
169 need to create and destroy extra users or print queues.  How to manage
170 cleanup of dynamic resources?
171
172 Requirements for running stf:
173
174     - Python, obviously
175     - Samba python extensions