Narrate Star Wars Movies with utPLSQL annotations

I recently played around a bit with the various utPLSQL annotations and found them pretty powerful.

I’m pretty sure I will write some more about how you can use annotations like --%beforeall or --%context to make your tests more expressive, but today I just want to showcase some techniques and tell the story of the original Star Wars movies.

For the interesting part is completely in the package specification I will skip the body in the highlighted code here. Each procedure implementation only contains a call to dbms_output.put_line with some text.

You can get the whole example as always from my github.

I create two test-packages, one parent package:

create or replace package sw_story_base as -- %suite(Star Wars: Movies) -- %beforeall procedure in_a_galaxy_far_away; -- %afterall procedure the_good_wins; procedure epic_intro; -- %beforeeach procedure deleted_scenes; -- %aftereach(deleted_scenes) end; / 

And one child package:

create or replace package sw_story_episode4_to_6 as -- %suite(Episode IV-VI) -- %suitepath(sw_story_base) -- %beforeall procedure clone_troops_are_bad; -- %beforeall procedure rebels_are_good; -- %test(Scene: Construction plans of the deathstar are stolen (Rogue One)) -- %beforetest(sw_story_base.epic_intro) -- %aftertest(rebels_flee) procedure rogue_one; -- %context(episode4) -- %displayname(Episode IV - A New Hope) -- %beforeall(sw_story_base.epic_intro) -- %beforeeach(c3po_is_afraid) -- %test(Scene: Rescue of princess Leia) -- %aftertest(death_of_obiwan) procedure rescue_of_leia; procedure death_of_obiwan; -- %test(Scene: Destruction of the deathstar) procedure destroy_deathstar; -- %aftereach procedure c3po_is_relieved; -- %endcontext -- %context(episode5) -- %displayname(Episode V - The Empire Strikes Back) -- %beforeall(sw_story_base.epic_intro,rebels_flee) -- %test(Scene: Battle for Hoth) -- %aftertest(rebels_flee) procedure battle_for_hoth; -- %endcontext -- %context(episode6) -- %displayname(Episode VI - Return of the Jedi) -- %beforeall(sw_story_base.epic_intro) -- %beforeeach(c3po_is_afraid) -- %aftereach(c3po_is_relieved) -- %test(Scene: Battle for Endor) procedure battle_for_endor; -- %endcontext procedure c3po_is_afraid; procedure rebels_flee; end; / 

Let’s look at the complete output of call ut.run(':sw_story_base') (with set serveroutput on) before I list some takeaways from this example

Star Wars: Movies In a galaxy far, far away Episode IV-VI Context: Clone troops are bad Context: Rebels are good Episode VI - Return of the Jedi An epic intro is shown Scene: Battle for Endor [,001 sec] C3PO is afraid Cute teddy-bears totally own the imperial troops C3PO is relieved Episode V - The Empire Strikes Back An epic intro is shown The rebels have to flee Scene: Battle for Hoth [,001 sec] Imperium wins the battle for Hoth The rebels have to flee Episode IV - A New Hope An epic intro is shown Scene: Rescue of princess Leia [,002 sec] C3PO is afraid Luke, Han and Chewie find Leia and escape Obi-Wan Kenobi dies C3PO is relieved Scene: Destruction of the deathstar [,001 sec] C3PO is afraid The deathstar is actually destroyed. C3PO is relieved Scene: Construction plans of the deathstar are stolen (Rogue One) [,001 sec] An epic intro is shown Rebels are able to steal the construction plans of the deathstar The rebels have to flee Finally, the good always wins. 

If we draw some boxes around suites, contexts and tests and highlight the different outputs based on the annotation that made them appear, we get this:

Takeaway 1: “each”-annotations are not called in child-suites

Although we defined --%beforeeach and --%aftereach in the sw_story_base suite, they are never called.

That is because there are no tests in the sw_story_base suite, but only in the sw_story_episode4_to_6, but beforeeach and aftereach are limited to tests of the same suite.

However, if they are defined on suite-level, they are also called for tests inside of contexts.

Takeaway 2: “before” and “after” annotations can be parameterized with method-references

All before and after annotations allow to be parameterized with references to procedures:

• beforeall
• beforeeach
• beforetest
• aftertest
• aftereach
• afterall

The referenced procedures don’t need to be in the same package but must be accessible.

Multiple references can be separated by comma and their order of execution is fixed.

Takeaway 3: You can reference the same method from different annotations

If you look at the rebels_flee procedure, it is referenced from several different annotations: beforeall and aftertest.

There is no limitation how often or from which annotations you can reference a method.

As you can see with deleted_scenes, you can even annotate a method with beforeeach and additionally reference it as aftereach (or any other before or after annotation).

Takeaway 4: You cannot rely on the order of contexts and tests, but on the order of setup and teardown

It’s obvious that our example messed up the order in which the different Episodes and Scenes are being called (there is even a new random test-execution functionality available since 3.1.7).

But the order in which the before and after methods are called is always fixed and you can totally rely on that.

So while you should aim to make tests and contexts independent from each other, you can guarantee their setup and teardown.

A request

I hope this little funny example showed you something new. If so, I’d love to hear about it.

But there’s another thing: I really wanted to create a little animation of that example-image where each step is highlighted together with the annotation that was used to call it. I sunk some hours trying to achieve it with PowerPoint but finally gave up frustrated.

If you know about any good and cheap tools that would help to explain stuff like this (for example by animated highlight/spotlight), please give me a hint.