10/06 2013

EXT:builder - yes we can!

A new Fluid Powered TYPO3 family extension is coming - this time, it's a support utility to further increase your productivity and ensure code quality.

Dear developers

A new extension is coming - EXT:builder. When installed in a development TYPO3 site (which is the only place it should ever be installed), this extension currently provides:

• A CLI command for syntax checking every PHP file in an extension - or a specific file. Useful for Phing / Travis / Jenkins scripts (internally uses PHP Lint checking so requires no additional code or modules in PHP; just the "php" CLI command).
• A CLI command for syntax checking every Fluid template file (formats can be specified). Will detect things like unclosed ViewHelper tags, unknown arguments). Can also output verbose information about templates - which Layout they use, for example. Planned additions in this syntax checker is to check if the Layout is present, if all Partials and sections are present and so on - to make detection of problems a breeze.
• A CLI command for generating ViewHelper unit test case classes for every class in an extension - or just a single class. The generated unit test cases cover about 50% of code that's present in standard ViewHelpers (injection, argument preparation, ViewHelperNode capability, etc). Planned additions include a generic way to test arguments - if arguments do not contain dynamic variables (and to the extent special classes can be supported) as well as a way to run PHPUnit immediately after creating a new test. With these coming improvements it is my hope that code coverage in auto-generated ViewHelper test cases can reach a fair 80% minimum and is able to provide instant feedback - thus finishing 80% of this particular task with a single command. Toggles for file overwriting behavior and dry run are provided. Generated classes are marked and can be automatically overwritten as the ViewHelper class they test are elaborated.

Each of these CLI commands use a parameter which can react to a single class or filename, making them ideal for use as triggered commands when saving files (or in file access monitors, scheduler tasks etc) to keep your back clear while you develop your extensions. They are also ideal for use in for example Travis build scripts, by fully automating tests of Github pull requests to validate PHP syntax, Fluid template consistency - or even on-the-fly generation of unit tests which cover newly submitted ViewHelper classes even before any actual unit tests get written.

The above is what the extension is currently capable of doing, but true to my nature I won't stop there. I also have loose plans to include:

• Annotation validation: defined Validator exists, used annotations (fx @var, @throws, @return) use proper and existing classes, etc.
• Unit test generation for Controller classes, including validation of annotations for validation, request has verification and so forth. Since Extbase Controller classes are very regular in nature, it's possible to use the Reflection framework to analyse methods and determine how a test should be constructed. While this is still just an idea, I have an expectation of being able to cover around 50%-70% of the code in Controller classes with automatically generated unit tests.
• Unit test generation for Utilities/Services/DomainObjects/Repositories which use simple argument values and expect simple return values. I expect to be able to reach a modest 80%-100% code coverage in these class types. Yes, it's true that much of this generation can happen in EXT:extension_builder, but there are some of us who prefer the manual way - or simply want to generate new unit test classes after initially constructing the extension in EXT:extension_builder.
• Kickstarting of "Fluid Powered TYPO3" extensions, page- and content templates - initially in the form of a CLI command but in time, perhaps also a BE module and perhaps even a graphical utility to go along with it, á la TemplaVoila.

The extension has not yet been published to TER and is still somewhere around beta stability, slightly lower. It still needs a bit of polishing before actual release but the features can be used safely on extensions that don't yet contain any ViewHelper unit tests (and of course the syntax checking commands don't modify files and can be always be used safely).

Clone the Github repository at <link https: github.com fluidtypo3 builder>github.com/FluidTYPO3/builder to your typo3conf/ext folder and install the extension. Clear all caches and execute in CLI:

localhost:mywebroot claus$ ./typo3/cli_dispatch.phpsh extbase help

...to see the list of commands. Then:

localhost:mywebroot claus$ ./typo3/cli_dispatch.phpsh extbase help <command>

...to see a list of supported arguments for each command. Try each one out, fix any warnings it gives about your code, generate a full collection of ViewHelper unit tests (currently covering ~50% of all ViewHelper code) - and enjoy the increased quality of your extension :)

Cheers,
Claus

PS: In a short time I'll be writing a blog article about using Travis Continuous Integration with Extbase/Fluid extensions - and supplementing the build script with the syntax checks provided by EXT:builder.