<div>

<p>

Good while ago I posted 

<a href="http://www.cincomsmalltalk.com/userblogs/cst/blogView?entry=3356098418">ResourcefulTestCase</a>

talking about a simplified pattern for test resources in the context of SUnit. Basic idea was that if you tend to group your test cases around their required resource you often end up with a package where many TestCase classes are mirrored with TestResource classes one-to-one. In this situation it is more convenient to simply use the class side of the TestCase class as its resource and cut the amount of classes by half. Moreover, various resource aspects can be placed into class side variables and conveniently accessed from instance side test methods.

</p>

<p>Recently I started using SUnitToo and wanted to try the same sort of pattern there. It turned out to be so simple, that it's not even worth adding a dedicated abstract TestClass to emulate the pattern.</p>

<p>To declare that a test class is its own resource simply add following (rather obvious) class method</p>

<pre>resources

^Array with: self

</pre>

<p>Two more methods are needed to make the resource work: #isAvailable and #reset. They can be directly used to for set-up and tear-down, although note that #isAvailable must return a Boolean. Just return true at the end of the method and you're set. You can return false to signal that resource failed to set-up but an exception will have the same effect.</p>

<p>Now, without repeating all the arguments, the original article recommends to use shared variables for various aspects of the resource. Here is the rest of an example of a hypothetical test resource:</p>

<pre>isAvailable

TestDirectory := '/dev/shm/testing' asFilename.

TestDirectory ensureDirectoryExists.

self generateTestContentIn: TestDirectory.

^true

</pre>

<p>And don't forget to nil out the shared variables in tear-down.</p>

<pre>reset

UnixProcess shOne: 'rm -r ', TestDirectory asString.

TestDirectory := nil.

</pre>

<p>

That's it. The only boilerplate code is the rather trivial and obvious 'self' in the 

<span style="font-weight: bold">resources</span>

method.

</p>

</div>

I've been using Linux as my primary desktop platform for some years now. I generally try to keep up with the releases and stick with the default choices as much as possible. Recently I tried to use F-Spot because it's the default photo manager for GNOME now. It's got some nice features and is generally OK, although not very flexible. Very much in the spirit of today's UI design dogmas ("You can't handle flexibility!"). Anyway, I noticed that F-Spot uses sqlite3 as its database, so I wasn't too afraid to spend some effort tagging pictures etc.

Recently, as I was upgrading my computers, I decided to move the pictures to a different location. Unfortunately F-Spot doesn't seem to provide a way to update its database accordingly. Poking around in the database it seemed to be fairly simple database update, so I decided to whip up a quick, Glorp based, database mapping and do the update with a script.

The database has a PHOTOS table with following definition:

CREATE TABLE photos (

	id			INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, 

	time			INTEGER NOT NULL, 

	base_uri		STRING NOT NULL, 

	filename		STRING NOT NULL, 

	description		TEXT NOT NULL, 

	roll_id			INTEGER NOT NULL, 

	default_version_id	INTEGER NOT NULL, 

	rating			INTEGER NULL, 

	md5_sum			TEXT NULL

);

The path to the picture is stored in the base_uri field, usually looking something like 'file:///home/user/Photos/...'. I needed to change all of them to something like 'file:///pub/photos....' instead. So, first I created a Photo class with a simplified version of the above:

	id  database id

	time  time taken

	base_uri  location of the photo

	filename  location of the photo

	description  any notes

Mappings are defined on subclasses of DescriptorSystem, so I created one and started with description of the class model:

classModelForPhoto: aModel



	aModel newAttributeNamed: #id.

	aModel newAttributeNamed: #time type: Timestamp.

	aModel newAttributeNamed: #base_uri type: String.

	aModel newAttributeNamed: #filename type: String.

	aModel newAttributeNamed: #description type: String.

then the table description.

tableForPHOTOS: aTable



	(aTable createFieldNamed: 'id' type: (self fakeSequenceFor: aTable)) bePrimaryKey.

	(aTable createFieldNamed: 'time' type: platform int4) beIndexed.

	aTable createFieldNamed: 'base_uri' type: platform varchar.

	aTable createFieldNamed: 'filename' type: platform varchar.

	aTable createFieldNamed: 'description' type: platform text.

and finally the mapping between the two:

descriptorForPhoto: aDescriptor



	| table |

	table := self tableNamed: 'PHOTOS'.

	aDescriptor table: table.

	(aDescriptor newMapping: DirectMapping) from: #id to: (table fieldNamed: 'id').

	(aDescriptor newMapping: DirectMapping) from: #base_uri to: (table fieldNamed: 'base_uri').

	(aDescriptor newMapping: DirectMapping) from: #filename to: (table fieldNamed: 'filename').

	(aDescriptor newMapping: DirectMapping) from: #time to: (table fieldNamed: 'time').

	(aDescriptor newMapping: DirectMapping) from: #description to: (table fieldNamed: 'description').

With these in place I could try to connect to the database. For that I needed to provide the connection information, so I added 2 class side methods:

newLogin



	^(Login new)

		database: SQLite3Platform new;

		connectString: (PortableFilename named: '$(HOME)/.config/f-spot/photos.db') asFilename asString.



newSession



	^self sessionForLogin: self newLogin

With this I could invoke #newSession and get a connected session back. Time to start experimenting with the database.

Reading a photo is easy:

	session readOneOf: Photo.

To figure out what are all the places from which I've imported pictures I used this:

	query := (Query read: Photo) retrieve: [ :e | e base_uri ].

	(session execute: query) asSet.

It reads all the base_uri values and puts them into a Set. A smarter database query can do this more efficiently, but this was fine as well in my database of about 6k pictures. I found out I imported pictures from two locations. I decided to deal with them one by one. To perform the update I ran the following:

	photos := session read: Photo where: [ :p | p base_uri like: '%home/mk/Photos%' ].

	session modify: photos in: [

		photos do: [ :p | p base_uri: (p base_uri copyReplaceAll: 'home/mk/Photos' with: 'pub/photos') ] ].

It reads each photo with the selected location in base_uri and updates it with the new one. Then I did the same for the second location. The entire update operation took less than 20 seconds. Later I found out that there's a plugin for F-Spot for this sort of migration, but its comment said that it can take a few hours. I don't know how big a database they had in mind, but that sounds a bit excessive still.

Since then I fleshed out the mappings, created a Glorp Workbook so that it's more convenient for quick experiments (you get a toolbar button for easy access) and packed it all up. I published the package to the public repository as F-Spot, hoping it might be useful to someone else too. As far as future plans go, there really aren't any beyond finishing the mapping layer. One thing I'm considering is that I find the imports into F-Spot excruciatingly slow. I might use this package for that task instead.

Our Seaside effort yields some useful byproducts including improvements to the, so far rather Spartan, WebSupport package. This package now provides HttpClient and HttpRequest extensions simplifying submission of HTML form data through HTTP POST method.

In general, form data can be submitted in a "url encoded" format in a simple, single-part HTTP request (content-type: application/x-www-form-urlencoded), or each data entry can be submitted as an individual part in a multipart HTTP request (content-type: multipart/form-data). Multipart messages are used when form data contains entries with relatively large values, for example when a form has external files attached to it for upload to the server. More information about HTML forms can be found at http://www.w3.org/TR/html401/interact/forms.html#h-17.13.

The default behavior of WebSupport extensions is to submit forms as simple requests. Form entries can be added individually using #addFormKey:value: message, or set at once using #formData: message which takes a collection of Associations. Note that #formData: replaces any previous form content. The following example

	stream := String new writeStream.
 	(HttpRequest post: 'http://localhost/xx/ValueOfFoo')
		addFormKey: 'foo' value: 'bar';
		addFormKey: 'file'  value: 'myFile';
		writeOn: stream.
	stream contents

yields this result:

POST /xx/ValueOfFoo HTTP/1.1
Host: localhost
Content-type: application/x-www-form-urlencoded
Content-length: 19

foo=bar&file=myFile'

An alternative way to post a form is through HttpClient, in this case the request gets automatically executed and the result is the response from the server.

	HttpClient new
		post: 'http://localhost/xx/ValueOfFoo' 
		formData: (
			Array
				with: 'foo' -> 'bar';
				with:'file' -> 'myFile').

To force the form to submit as a multipart message, send #beMultipart to the request at any point. Any previously added entries will be automatically converted to message parts. Note however that conversion of multipart messages back to simple messages is not supported, as it is not always possible without potentially losing information.

	stream := String new writeStream.
 	(HttpRequest post: 'http://localhost/xx/ValueOfFoo')
		beMultipart;
		addFormKey: 'foo' value: 'bar';
		addFormKey: 'file'  value: 'myFile';
		writeOn: stream.
	stream contents

and the result is

POST /xx/ValueOfFoo HTTP/1.1
Host: localhost
Content-type: multipart/form-data;boundary="=_vw0.98992842109405d_="
Content-length: 183

--=_vw0.98992842109405d_=
Content-disposition: form-data;name=foo

bar
--=_vw0.98992842109405d_=
Content-disposition: form-data;name=file

myFile
--=_vw0.98992842109405d_=--

File entries can be added using message #addFormKey:filename:source:. Adding a file entry automatically forces the message to become multipart to be able to capture both the entry key and the filename.

	stream := String new writeStream.
	(HttpRequest post: 'http://localhost/xx/ValueOfFoo')
		addFormKey: 'foo' value: 'bar';
		addFormKey: 'text'  filename: 'text.txt' source: 'some text' readStream;
		writeOn: stream.
	stream contents

POST /xx/ValueOfFoo HTTP/1.1
Host: localhost
Content-type: multipart/form-data;boundary="=_vw0.015112462460581d_="
Content-length: 247

--=_vw0.015112462460581d_=
Content-disposition: form-data;name=foo

bar
--=_vw0.015112462460581d_=
Content-type: text/plain;charset=utf_8
Content-disposition: form-data;name=text;filename=text.txt

some text
--=_vw0.015112462460581d_=--

Adding a file entry attempts to guess the appropriate Content-Type for that part from the filename extension. If it doesn't succeed the content type is set to default, i.e application/octet-stream. File names with non ASCII character will be automatically encoded using UTF8 encoding. UTF8 will also be used for the file contents if the source is a character stream (as opposed to byte stream).

Adding an entry to a multipart message returns the newly created part. That allows to modify any of the default settings or to add new ones. Here's an example changing the filename and file contents encoding to ISO8859-2:

	stream := String new writeStream.
	request := HttpRequest post: 'http://localhost/xx/ValueOfFoo'.
	part := request addFormKey: 'czech'
				filename: 'kůň.txt'
				source: 'Příli¨ ¸luťoučký kůň úpěl ďábelské ódy.' withCRs readStream.
	part headerCharset: #'iso-8859-2';
		charset: #'iso-8859-2'.
	request writeOn: stream.
	stream contents

POST /xx/ValueOfFoo HTTP/1.1
Host: localhost
Content-type: multipart/form-data;boundary="=_vw0.74617905623567d_="
Content-length: 228

--=_vw0.74617905623567d_=
Content-type: text/plain;charset=iso-8859-2
Content-disposition: form-data;name=czech;filename="=?iso-8859-2?B?a/nyLnR4dA==?="

Pøíli¹ ¾lu»ouèký kùò úpìl ïábelské ódy.
--=_vw0.74617905623567d_=--

There's also an API to parse messages containing forms in any of the supported forms. Just send #formData to the HTTP message. The result is a collection of associations, the same form as the input to the #formData: message.

 	(HttpRequest post: 'http://localhost/xx/ValueOfFoo')
		addFormKey: 'foo' value: 'bar';
		addFormKey: 'file'  value: 'myFile';
		formData

OrderedCollection ('foo'->'bar' 'file'->'myFile')

File entry values will be entire message parts so that all the associated information can be accessed.

	request := (HttpRequest post: 'http://localhost/xx/ValueOfFoo')
		addFormKey: 'foo' value: 'bar';
		addFormKey: 'text'  filename: 'text.txt' source: 'some text' readStream;
		yourself.
	part := request formData last value.
	part contents

some text

If you'd like to give the new code a try just load it up from the public repository.

The core SUnit package provides support for shared test resources via the TestResource class. A TestCase that wants to use TestResources is expected to list all its resource classes in its class side #resources method. Individual test case methods then access the resources via the resource classes, usually as default, singleton instances. That provides potentially interesting levels of flexibility, however the access to the resources themselves is not exactly convenient. In my experience vast majority of cases involving TestResources either keep repeating the 'self resources first default blah' incantation over and over again, where blah is the name of the real resource the case cares about which is being managed in a blah instance variable of the corresponding TestResource subclass. A more palatable way is adding the same instance variables to the TestCase subclass as well and copying the resource pieces there in the TestCase>>setUp method. Then you can access the resources directly as instance variables in your test case methods. This way the test methods are clean again, but when you want to employ test resources you still have to go through the following sequence of steps:

1. create a TestResource subclass
2. add it to the TestCase class>>resources method
3. add the same set of instance variables to the TestCase subclass
4. copy the contents of the TestResource default instance to the TestCase instance variables in TestCase>>setUp method

Naturally as you realize you're doing this over and over again, you start thinking, wouldn't it be nice if you didn't have to. My first thought was, what if the TestSuite that gets built out of a given TestCase subclass didn't simply create empty TestCase instances, but instead first created a prototype instance, invoke something like #suiteSetUp on it, which would allow to initialize the shared resources and put them directly into the instance variables of the case prototype. Then all the test cases would be built by simply copying the prototype instance and therefore would have the resource inst vars automagically initialized the same way as the prototype. Tear down could be performed by invoking #suiteTearDown on either the prototype or any of the cases. It doesn't really matter which one, you just have to make sure it is executed exactly once.

Of course while I was enjoying myself following this thread of thought, I forgot one important detail. TestCase instances are not created just before the suite runs. They are often created much much earlier. That of course directly conflicts with the desire to initialize the resources just before they are needed and shutting them down right after the run is complete. I was just about to descend into yet another desperate attempt to rewrite most of SUnit when Alan Knight, who happened to be traveling with me at that moment, responded to my loud complaints with simple: "Just put them into class variables."

And so the ResourcefulTestCase was born. It is an abstract TestCase subclass with simplified support for shared test resources. Instead of separate classes of test resources, it makes sure that if there are class side #setUp and #tearDown methods defined on the class, they run before and after the test suite that gets built out of this test class. This allows one to initialize and store shared resources in class side variables in the #setUp method. It's probably easiest to use shared class variables for easy access from the instance side test case methods. I also like that the capitalized first letter nicely highlights in the test code the difference between the shared resources and the private stuff in case instance variables. Obviously the resources need to be torn down in the class side #tearDown method. It is usually also desirable to nil out the variables as well so that the class doesn't hand on to garbage. The nilling out could be done automatically with a bit of meta-programming, but since it's often also important to finalize/close/release the resources properly as well, I figured it's better to force the user to deal with that, rather than facilitate potentially serious leaks with more automated magic. It's probably also a good idea to call super implementations of the setUp/tearDown methods so that case hierarchies work well.

Here's a quick summary of how to create a test case with resources:

1. Make the test class a subclass of ResourcefulTestCase:

   XProgramming.SUnit defineClass: #MyTest
   	superclass: #{XProgramming.SUnit.ResourcefulTestCase}
   	indexedType: #none
   	private: false
   	instanceVariableNames: ''
   	classInstanceVariableNames: ''
   	imports: ''
   	category: 'My Tests'
   
   

2. Add class variables for the shared resources.
3. Add class side setUp method and initialize the test resources there

   MyTest class>>setUp
   
   	A := Object new.
   	Client := HttpClient new connect: 'testserver'
   
   

4. Add class side tearDown method releasing the resources

   MyTest class>>setUp
   
   	A := nil.
   	Client close.
   	Client := nil.
   
   

And that's it. All nicely and intuitively packaged in a single class. Now you can simply use the resources in your test methods:

MyTest>>testResources

	self assert: A class == Object.
	self assert: (Client get: 'index.html') isSuccess

We've set up a new blog for the Cincom Smalltalk engineering team - expect to find technical posts here that cut across the entire Cincom Smalltalk product line. I'll be making some modifications to the blog server so that posts from some of the individual blogs get cross posted here automatically - that's going to take a little work to get right. In the meantime, enjoy the new site!