Tuesday, 26 February 2008
Oops
Monday, 11 February 2008
Inka moved
Also, I'm finally building me a site, and there'll be a lot about Inka and how it should be used. Find it at http://sm-art.biz.
Saturday, 12 January 2008
Inka Layout, take three
In short, first I tried Need Driven development: implement it step by step, mocking out the next step before implementing the current. This became a disaster: too much upfront design for me. Without seeing the whole picture, I was never sure that it works, much less that it works the way it should.
My second attempt was much better. At least it began better. I implemented a quick and dirty solution first, then added a few more integration tests and made my solution a bit more complex, then began to refactor. The refactoring stage took forever though. I still haven't finished it in the last release, so I was too shy to publish the code. With only integration tests in place, I wasn't seeing the correct direction of refactoring, so I was doing it blindly, and it took ages to figure out why this particular test broke when I did this simple refactoring.
Now it's the third attempt, and I've already abandoned version 3a. But I don't want to talk about it yet, until I see the results. I should say that the trunk version is the same as used in the last release, since I decided to put the new experimental version in a separate branch.
Saturday, 10 November 2007
Inka (formerly Freshreports) 0.6.1 is out
The bad news is that you have to group your records yourself. The good news is that with Linq it is trivial (see the example application). After that, you add the outer section (that corresponds to the group header/footer in the traditional scenario), and the inner section to the outer one. The grouped data source should be applied to the outer section, which is of type GroupSection, and the inner section and the elements of the outer section get the correct data sources automatically.
See the Data.doc and the sample application included in the download.
I should confess that I didn't try it with a more than 2 level scenario.
Tuesday, 6 November 2007
FreshReports is now Inka
For a while I thought about something trivially Arabic, like Mustafah. But I wanted something related to printing, so here it is -- Inka. Sounds romantic, too.
Sunday, 14 October 2007
FreshReports 0.6 is out
In fact, I made paging work from the third attempt. First time I took the path of Need-Driven Development, as I understood it. Namely, instead of writing a functional test, I worked step by step and mocked the stuff I planned to add later. The result was a disaster -- I quickly lost all understanding of what works and what is left to be implemented yet. So, at some point I decided to hit the "delete" button.
Second time I did it better. I already had a Page class that held all the element positions in a hashtable. I was pretty sure that once an element appears in this class at a correct position, it should be printed correctly. However, I was treating "unbreakable" sections (ones that cannot be split across pages) as single elements (thus having a single entry in this hashtable). Once I had all the possible tests i could think of pass, I was pretty sure that I got it.
Well, I launched my test application and promptly discovered that everything is printed at wrong positions even if it fits on a single page!
Had to start again.
This time I decided to keep that hashtable, but now I keep all the individual elements' positions there, not sections.
This change broke about half of my tests. I suspected that my tests are a mess, but not that much. Turned out that most of them are not "unit" enough, nor integration. I remember that I should refactor my code, but I'm forgetting about refactoring my tests.
Anyway, I think I've nailed it this time. The code is very ugly at the moment, so I'm not releasing it. I'll be refactoring it as well as add some additional checks about stuff like page margins and such. Probably the next release will see the section margins as well, to get finished with the layout features. But the most important things now are grouping support and aggregates.
Saturday, 1 September 2007
Interaction vs stateful tests, or Falling for Need-Driven Development
So, how do you do it with NDD? First, you formulate the story, as always. Mine is, "Suppose we have two sections in our report, then if the second doesn't fit on a page, it goes to the next page". Next, I start to code the Page' s CalculateLayout method, something like this:
For Each section In sections
If section.Fits() Then
'do something about it
So, we want to code the CalculateLayout method and not get distracted by the Fits method, which is probably a lot to code, so we just mock it out and get a green on CalculateLayout. Next we switch to the Fits method which probably depends on something else, so we mock this something and proceed with the Fits method until it's perfect.
This technique seems fine from a traditional development's point of view. In fact, it is more or less design-first approach. But when I tried to move this way, after programming the TDD way for some time, I was feeling very uneasy. In the TDD fashion, I should have made a simple test that covers everything (section setup and printing), and mocked just the call I am sure of (to the actual element printing method) (note that I could have mocked the call to the section's Print method instead and save time on adding elements to the sections, but only if I'm sure that it works fine with paging). With NDD, I had to write tests for several steps, and since I don't see the whole picture from the start, I don't even know how soon I get to the actual printing. With TDD, I would have let my tests do the design for me, and even while writing the first test I would have discovered that I need a separate Pager class. With NDD, I sort of know the design of the current step before I start writing the test, and that's wrong, because, for example, later I discover that my Fits method needs two additional arguments, and changing its signature will break my tests.
Why have I fallen for it? Partly because I just read an article in which some obviously smart guys told me it's good. Partly because it's tempting. In my case, while writing the first test, I didn't know how to setup this "doesn't fit" idea, so I just mocked it. It was quite easy to write a test, even easier to write the production code, but after that I didn't feel I achieved something, quite the opposite, I felt that I've just made things more complicated. So you see, it's all about feeling good or bad, so it's quite personal.
So, is it that bad? Of course, not. NDD is great for more structured guys. I was feeling helpless because I didn't have a clear picture of what's happening, but that's just me. I prefer to do something quick in a very chaotic way, and then refactor it to make it more structured. NDD is for those who prefer to move step by step.
In fact, I'm using NDD when I encounter an external dependency, such as FTP or file system. I resist a temptation to just save a file, instead I code an interface and use it. I still have to remember to implement it later, but at least it's an end point rather than part of a long chain of objects. So, to avoid this temptation, I made a rule for myself: never mock an interface you haven't implemented yet, save for such thin implementations of external dependencies.
Thursday, 30 August 2007
FreshReports: elements and sections
Most readers are familiar with traditional reporting components, starting with MS Access reports. Using this analogy, our sections correspond to traditional details and group/report headers/footers. However, in traditional reporting we typically have database rows pulled by some inner join query, so the data is essentially flat. FreshReports, on the other hand, uses object graphs as data, so we can have tree-like structure of sections inside other sections.
FreshReports have a notion of "design time" or "template" section. This is essentially the section definition. Think of it as object representation of the section definition you see in the designer. At runtime, it generates one or several identical clones, named "runtime sections" (or sometimes "detail sections"), according to its data source. This data source corresponds to a table or query result in the traditional reporting scenario, while the DataItem property corresponds to a database row. Individual elements display properties of the DataItem. Note that an element can display several property values mixed with text (the syntax is very close to that of MS Access).
Sections can be broken between pages in 3 different ways, according to the KeepTogether property. The first way is no limitation. If some elements don't fit on this page, they go to the next. At this point, it's not very useful: these elements are going to be printed not at the top of the page but at the same shift from the top of the section. But anyway a typical section is a row of elements, so they won't break to the next page. A more useful scenario is when a section contains some elements and another section. But anyway this is going to work properly only when I implement pushing -- this is when some elements "push" others when they grow.
The second possibility is to keep each runtime section together. And the last is to keep the whole section (all its clones) on one page.
At some point it's going to turn into a set of customizable rules (for example, you'll be able to keep several sections on one page -- useful for table headers).
Note that the features described here are scheduled for the 0.5.1 release.
Monday, 27 August 2007
FreshReports 0.5 is out
So far, it can print just simple data. Stuff like "[Name]' age is [Age]". Note that this is already ahead of the report engines I've seen: we have two properties in one data element! Note also that I don't use curly brackets. I'm trying to make it as simple as it can be.
If you need to print the object itself, rather than its property, use an empty property name, like this: "This is []". It actually uses the object's ToString() method.
The main usage pattern is like this:
1. Create a Report object.
2. Create the layout (in the future releases it will be possible to load it from an XML file).
3. Add a data source (or several).
4. Print().
Happy printing!
Wednesday, 15 August 2007
Adventures in test-driven development Part 4: What's next?
1. Test-first: write a test, watch it fail, write the simplest (production) code to make the test pass (you can even hardcore some constants in your code), then refactor in smallest possible steps while keeping the test (and the other tests) pass. This is referred to as Red-Green-Refactor cycle.
2. Test-driven: when your testing is too complex, don't just sigh and accept it. This is a sign that your design can be improved. Let the testing drive your code.
3. YAGNI -- you ain't gonna need it. Instead of implementing a Good Thing just because it is one of the GoF patterns or you've just read it in somebody's blog, whatever makes your tests pass is OK. You see that this method you just wrote is ugly, but wait until the next test drives you in the right direction for refactoring. There's another similar principle, KISS (Keep It Simple, Stupid).
4. Separation of Concerns (SoC) principle -- each object has to have a distinct responsibility. Keep in mind, though, that this is just a clue: whenever you have problems with testability and you don't know what to do, try this or some other design idea (see Dependency Injection below) and see if it simplifies things. The general idea is that you don't apply these patterns or principles blindly, but let your tests decide what to apply.
5. Dependency Injection. We have seen it when we were getting rid of the Graphics dependency. The main idea is that it is very hard to test your class when there's an external dependency involved, such as an SMTP server, local file system, or some unmanaged stuff. So, don't hardcore it into your component, have it "injected" somehow in your production code, and mock it in your test code to make sure that your code interacts correctly with it. Again, the "weakness" of our mock framework dictated this. But this is not just designing for testability -- turns out that it opens a possibility for other reporting options -- exporting to HTML, Word, or maybe projecting onto a Star Wars style transparent screen.
This is no accident that Rhino Mocks forced us for a better design. While TypeMock does its job by applying some sort of black magic, Rhino plays by the .Net rules: overrides virtual methods, extends classes, implements interfaces -- does what you or users of your component would do to extend it.
So, while I'm not going to publish all the details, I'm going to share all my big moves and discoveries, especially TDD-related. The latest source of FreshReports can be found in the SVN repository at SourceForge at https://freshreports.svn.sourceforge.net/svnroot/freshreports/trunk.
Further reading:
TDD Design Starter Kit by Jeremy D. Miller
Achieving And Recognizing Testable Software Designs by Roy Osherove
testdrivendevelopment group on Yahoo
Friday, 10 August 2007
Adventures in test-driven development Part 3: Getting Rid Of the Ugly Stuff
In order to test our behavior and not print something in the process, we need to mock the Graphics object. However, it is impossible with Rhino, since the class is sealed, or NotInheritable. So, somehow we should eliminate this hardcoded dependency from our class.
Why is this good, apart from testability? First, the Graphics class is a heavy dependency. The sole fact that it is IDisposable tells us that it depends on some unmanaged resources. In addition, it brings a dependency on Win32, which is bad, since we want to develop a universal component. Sure if we want to use our component on Mono or whatever CLR implementation exists, we could find a Graphics analog, but there's no guarantee that these implementations, that are not part of the standards, are implemented the same way.
Also, it carries too much with it that we just don't need. We don't want our main object perform all the low-level work, we want to serve it as a main controller, leaving all individual details to other objects.
Therefore, we are going to introduce a Canvas class, which is going to serve as our main printing device. Immediately, we have two advantages. First, we can provide multiple inheritors of the Canvas class, so, in theory, we can print to PDF, HTML, Word, anything. Second, we are ruling the interface of our Canvas class. Whenever we look at it, we immediately know its responsibilities within our project. We don't have to adapt to the Graphics interface (this is done in the implementation). Since we don't need mysterious stuff that Graphics has, like GetHdc() or FromHwndInternal(), we don't include it as part of our class, so those who use our component won't be tempted to play with it.
Enough said, let's code! Before we even start with our second test, we should do a little redesign.We should move in small steps, running our test after each step. This way we immediately know if we make a wrong step. Remember that RhinoMocks requires that we mock an interface or an inheritable class. The first step is to construct a thin wrapper around the Graphics class, giving out just the methods we need. Let's call it GraphicsCanvas, and let's put it into WinForms namespace. This is the only namespace that is going to reference the System.Drawing assembly, and eventually we are going to extract it into a separate project. Although it seems like adding complexity, actually it makes our design cleaner, since the project itself becomes clean of "the earthly stuff" in some way. For the same reason, I'm going to introduce my analog of the System.Drawing.Point structure.
The first step is, unfortunately, relatively big. We have to write some basic stuff into our new class so that we have something to test. Let's have it:
Namespace WinForms
Public Class GraphicsCanvas
Private _graphics As Drawing.Graphics
Private Sub New()
End Sub
Public Sub New(ByVal graphics As System.Drawing.Graphics)
Me._graphics = graphics
End Sub
Sub DrawString(ByVal text As String, ByVal position As Printing.Point)
Me._graphics.DrawString(text, New Drawing.Font("Verdana", 8.0, Drawing.FontStyle.Regular), Drawing.Brushes.Black, 0, 0)
End Sub
End Class
End Namespace
What do we have here? First, we hold a private variable for our Graphics object. Next, we have a private parameterless constructor, which makes it impossible to construct our class without parameters. Indeed, it cannot exist without the Graphics object. Next, we have a public constructor. I should say here that while the class itself and the constructor can reference the Graphics class, all other public methods shouldn't, since we are going to convert them into an interface later. So, the last is our first printing method. The least we should provide for printing is the text and its location. In fact, it's about 90% of our needs, or close to that.
Now, let's figure out our testing strategy. The way Rhino Mocks, as well as most other mock frameworks, work is quite different from TypeMock. TypeMock places a sort of hook on a class before the concrete object is created, so that when it is created, some method calls can be intercepted. So, it's fine that the object itself is created somewhere in our code. Just like the Graphics object, which is created somewhere deep in the framework. On the other hand, a Rhino Mocks mock should be created explicitly in the test. That forces us to redesign our code, so that we could somehow feed the mock object into our production code. This is done via constructor arguments, property setters, or method parameters. This procedure is generally called "dependency injection".
In our case, each page corresponds to a separate Graphics object, so it makes sense that we provide a separate GraphicsCanvas object for each page. So, the first refactoring is to extract the call to DrawString() to a separate method:
Protected Overrides Sub OnPrintPage(ByVal e As System.Drawing.Printing.PrintPageEventArgs)
Me.PrintCurrentPage(e.Graphics)
End Sub
Sub PrintCurrentPage(ByVal graphics As System.Drawing.Graphics)
For Each section In Me.Sections.Values
For Each element In section.Elements.Values
graphics.DrawString(CType(element, Elements.LabelElement).Text, New Drawing.Font("Verdana", 8.0, Drawing.FontStyle.Regular), Drawing.Brushes.Black, 0, 0)
Next
Next
End Sub
In our second test, we are not going to call the Report.Print() method, since there's no way to inject the Canvas dependency. Instead, we'll call the PrintCurrentPage, but only after we figure out how to call it. So, this method should take our wrapper as an argument. The next version looks like this:
Protected Overrides Sub OnPrintPage(ByVal e As System.Drawing.Printing.PrintPageEventArgs)
Dim canvas = New WinForms.GraphicsCanvas(e.Graphics)
Me.PrintCurrentPage(canvas)
End Sub
Sub PrintCurrentPage(ByVal canvas As WinForms.GraphicsCanvas)
For Each section In Me.Sections.Values
For Each element In section.Elements.Values
Dim Text = CType(element, Elements.LabelElement).Text
canvas.DrawString(Text, New Fresh.Printing.Point)
Next
Next
End Sub
What are the requirements for the type of the canvas argument? First, it should allow us to pass our GraphicsCanvas object, so it should be a base class. Second, it should be mockable. In addition, it should provide our base functionality (the DrawString method) without implementing it (so the method should be abstract, or MustOverride). So, it's either an abstract class or an interface. Typically, such things are done with interfaces. Perhaps historically mock frameworks could work with interfaces but not with abstract classes. For me, an interface is some common functionality among unrelated classes (like IDisposable), whereas an abstract class is a conceptual common ground, like Shape for all geometrical shapes.
So, let's shoot our Canvas class:
Namespace Printing
Public MustInherit Class Canvas
MustOverride Sub DrawString(ByVal text As String, ByVal position As Point)
End Class
End Namespace
Sub PrintCurrentPage(ByVal canvas As Printing.Canvas)So, did it make our design better? First, we have greater control over printing. We have extracted our PrintCurrentPage method and now can call it directly. This is a big step towards being independent from the PrintDocument class by the way. Next, we can print to anything we like, provided we can implement a custom Canvas class. Our main Report object has been relieved from the printing burden, and can concentrate on more important tasks (such as handling the report structure and routing commands to other objects). This is called the Separation of Responsibilities (SoC) principle.
Finally, let's see our test:
First goes some preparation. Next we have a Using mocks.Record statement -- it's a first part of the Record-Replay pattern, where we first write down what method calls we expect, what arguments should be there, and which results should the methods return. In our case, the first line states that we should call the DrawString method. The arguments are irrelevant here, but without them the code won't be compiled. The second line tells us that the first argument should be equal to our test string, and the second can be anything.<Test()> Sub TestWithRhino()
Dim mocks As New MockRepository()
Dim canvasMock = mocks.CreateMock(Of Printing.Canvas)()
Dim TestReport = New Report
Dim TestSection As New Core.Section
TestReport.Sections.Add("", TestSection)
Dim TestElement As New Elements.LabelElement
TestSection.Elements.Add("", TestElement)
TestElement.Text = "test"
Using mocks.Record
canvasMock.DrawString("", New Printing.Point()) 'we can provide any arguments here
LastCall.Constraints(Rhino.Mocks.Constraints.Text.Like("test"), New Rhino.Mocks.Constraints.Anything)
End Using
Using mocks.Playback
TestReport.PrintCurrentPage(canvasMock)
End Using
End Sub
Last, we have a Playback block where we put our tested method.
Our test actually verifies that the appropriate call is made to the Canvas object. It doesn't verify that the string is actually printed. This is where Rhino Mocks can't help us. However, we can easily write a separate test (using TypeMock) for it. Since we have two separate objects, we can test them independently. We can do all kinds of tests verifying that DrawString is invoked correctly, and only one test verifying that it actually prints something. When we have other Canvas objects, we'll have to make one test for each object, instead of testing all possible report layouts and data with each canvas. That's what the term unit testing is about.
Another thing that's not tested here is that calling the Print() method actually calls the PrintCurrentPage method. So far, we have our first test to verify it, but this is an indication that this piece has to be refactored as well. I guess I'll be making a separate class ReportPrinter that inherits from PrintDocument and manages the interaction with the actual printing and previewing (it can even be used at design-time in a form), and our Report class will be completely ignorant of these implementation details. However, I'll wait till I implement paging and let my tests drive my design.
Thursday, 2 August 2007
Adventures in test-driven development Part 1, first mistake
So far, everything looks so wise. Until I try to write my first test. It's supposed to be pretty straightforward: just print the word "test". However, when I try to write it, I discover that I even don't know my API! I don't have my ICanvas interface, much less its implementation, I don't have a Print method, and I don't know how to glue these things together.
So, although I already knew that I shouldn't design upfront, somehow I got into this trap again. I've been lucky that I haven't written much code before realizing that.
Now I'm going to do it by the book. Just find the simplest way to print a word and do just that. The really simplest way, it turns out, is to inherit from the PrintDocument class and override the OnPrintPage method. Then use the Graphics object to print stuff. For the moment, I have to forget all the elegant objects I invented, and follow the ugly (but quick) path. I even hardcode the word "test" in my code!
But before I do, I should write the test. Mocking Graphics isn't the simplest thing in the world, but with a little bit of Reflector I produce the following piece of code:
Imports TypeMockA few comments here for those who's not familiar with TypeMock. It creates a Mock object that "waits" till a real object of this type is created, and then "hooks" on it and lets us watch/catch/stub/fake method and property calls to this object. This contrasts to the other frameworks and also manual mocking, where you have to manually create an object which replaces the "real" object. Notice that we are mocking a Graphics object which is created somewhere deep in the System.Drawing.Printing namespace. Since the Microsoft's design is (as always) utterly untestable, we can't feed our own mock object, so our only option is trick the code with the help of TypeMock. So, first we create a mock for Graphics, then we tell it that we expect a call to the DrawString method, and that the first argument should be "test", and the rest can be anything. Same with the SystemFonts object, but we also tell it that it should return a specific value.<TestFixture>Public Class Tests
<Test, VerifyMocks>Sub PrintSimpleText()
Dim graphicsMock = MockManager.Mock(Of Drawing.Graphics)(Constructor.Mocked)
graphicsMock.ExpectCall("DrawString").Args("test", Check.IsAny, Check.IsAny, Check.IsAny, Check.IsAny)
Dim SystemFontsMock = TypeMock.MockManager.Mock(GetType(System.Drawing.SystemFonts))
SystemFontsMock.ExpectGetAlways("DefaultFont", New System.Drawing.Font("Verdana", 8))
Dim TestReport = New Report
TestReport.PrintController = New Drawing.Printing.PreviewPrintController
TestReport.Print()
End Sub
End Class
Now, my production code would be:
I've got a green, I'm happy for today, and I'm particularly ecstatic about having the word "test" hardcoded in my production code.Public Class Report
Inherits PrintDocument
Protected Overrides Sub OnPrintPage(ByVal e As System.Drawing.Printing.PrintPageEventArgs)
e.Graphics.DrawString("test", New Drawing.Font("Verdana", 8.0, Drawing.FontStyle.Regular), Drawing.Brushes.Black, 0, 0)
End Sub
End Class
What I'm not happy about is that ever since I upgraded to TypeMock version4, my Zanebug GUI won't run with the TypeMock runner. So, I had to switch back to NUnit. I don't know about their engines, but I feel quite uncomfortable with the NUnit GUI. OK, it's personal.
What's next? The next useful feature seems to be the ability to print any text we want, not just the word "test". This is going to be the topic of the next post.
Adventures in test-driven development, Introduction
My toolbox:
Visual Basic 2008 Express Edition (I'm going to miss the TestDriven.Net add-in a lot!)
Adaptev's Unit testing framework and Zanebug (I don't know why I prefer it over NUnit)
TypeMock -- it saves a lot of testing efforts
RhinoMocks -- I was told that it "enforces good design", so, although I don't like being enforced, I decided to try it and see the design it enforced.
Now, let's start!