Guardian Pub

The Guardian is the continuous testing and continuous integration facility. It runs all the stories virtually all the time - whenever there is a change to either the stories or specs, or to the target environment.

The status is either green or red and the detailed report is available if you click on it.

When to test

The Guardian has a few operating modes:

  • manual, from the menu - you can start a few testing scenarios
  • auto, when some configuration (specs, stories) changes
  • scheduled, when monitoring a service and detecting a change

Note that auto is generally turned off for diesel cloud++ deployments.

Manual mode

As a "mod" or "admin" of a project, you will see a "Guardian" menu with a few drop down options (Test Sanity or Test All). This will kick-off a "guardian test" which will run all the configured stories and report. If there was already a test run in progress, it will nagivate to it's status instead of starting a new one.

Auto mode

The guardian can also be set to auto mode, where it runs the entire test suite as you save changes to stories and specs. This is turned off by default. Configuring the auto mode works only in local environments, by configuring a few things:

  • enabling the guardian with the config property set to "true"
  • setting the config property to true.
  • running in localhost mode (see Running locally via Docker)
  • set that deployment in "dev mode" with setting the config property wiki.devMode to "true"

This one's tricky and can add a lot of overhead, so it's turned off by detauls, we prefer the scheduled version.

Configuring the scope to test

The Guardian will look at all the topics in the current reactor that match a pre-configured Tag query++ guardian.settings.query, configured in the Reactor configuration.

A good example would be (a few stories tagged sanity is a great idea for automated testing):


You can override this setting and pass this tagQuery argument into the polled message when you poll a certain environment for changes, see about polling below (the drawback is that this setting will only override the scheduled tests, not others - the guardian may also start automatically or on demand and those only use the guardian.settings.query):

=>, stamp="Etr:${t1}", tagQuery="story/sanity/-skip/-manual")

Also, the Guardian will re-run all tests when a topic matching these criteria is edited/changed:

  • are in the Spec or Story categories
  • are tagged spec or story

Note the tag query above story/sanity/-skip will include all stories tagged sanity and NOT tagged skip.

The convention for tags are:

  • sanity marks sanity test cases
  • skip use it to temporarily skip specific test cases
  • manual these tests only run when the user manually runs them

However, you can customize the default guardian's tagQuery as above.

Polling and scheduling

Note: this is specific to the Guardian. For a more generic scheduling mechanism, see diesel.cron.set.

The Guardian can watch several systems and trigger specific test suites when these systems are updated. This is how the guardian keeps everything on the level via continuous testing but without overwhelming all systems.

The Guardian poller will keep a stamp for each environment and it will poll the environments on a schedule, to get this stamp. When the stamp changes, the poller will initiate a test and record the test results.

Good values for the stamp are build numbers, release numbers, build timeStamps, git commit IDs etc.

These are set for each Environment settings and require three parts:

Here's an example of schedules, configured per environment when the realm is loaded:

A) scheduling

$when diesel.realm.loaded
=> (env="sandbox", schedule="5 minutes")
=> (env="dev", schedule="5 minutes")

Using a differnt realm: you can run the schedule in a different realm by passing inRealm=whichone - this only works for trusted realms, see setting in Reactor configuration. This option is good when testing a production reactor from a schedule running on a development reactor.

Also, by passing in inLocal=yes you can have schedules that only run in a "local" deployment, i.e. not in the dieselapps cloud. This is very useful when accessing environments only available from the local - these tests would always fail ran from the cloud!

When the schedule kicks in, every 5 minutes, a message is created and you have to handle it to poll the external system.

This is a typical poll, which you have to configure as the implementation for the reserved message - this one pings an environment-specific URL which returns a json document with a buildTimestamp:

B) polling the target

=> diesel.setEnv(env, user=diesel.username)
=> snakk.json (url=GUARDIAN_PING_URL)
=> (payload = payload.buildTimestamp)
=>, stamp=payload)

The target system in this case implements a GUARDIAN_PING_URL which returns a JSON document. This JSON document has a field buildTimestamp which can be used to determine when new code has been deployed. When new code is detected, then the guardian will automatically start a test.

The internal implementation of will compare the current timestamp with the previous stored values and decide if a new test should be executed or not. If true, it will schedule a new test in that environment.

  • for you can add these parameters (, stamp, inRealm?, tagQuery?)):
    • the stamp is the new signature extracted from the target environment, it will be compared with previous and if different a new run scheduled
    • inRealm="myotherproject" to notify it to be ran in another trusted realm, see You'll need to setup a trust relationship between the two projects.
    • tagQuery="Story/sanity/-skip/-manual" you can override the default guardian.settings.query with a specific set of tags to test

At the end of a test run, the Guardian will decide if a notification needs to be sent, depending on the current test status and the previous tests (if it's still successful, then no notification is sent).

If the Guardian needs to send out a notification, you have to configure the notification. A typical notification goes to an email - note that you can send to different emails based on the environment, in this case sandbox:

$when (realm, env == "sandbox", oldStatus, newStatus, errors, total, report)
=> diesel.mail.send (
    subject = "${errors} / ${total} Guardian errors in "+env, 

Configuration per environment

The accepted pattern for configuring various environments is using diesel.setEnv like so:

C) configuring the environment

$when diesel.setEnv(env is "dev", user)

$when diesel.setEnv(env is "prod", user)


When running a test, the stories are ran in alphabetical order, so the easiest way to organize them is with their name. It is important to be able to control the order of the tests, so that creation tests for instance run before query tests etc.

However, you can also use tags: any tag starting with "testOrder" will be used to sort, before the name. So for instance story "A2" with tag "testOrder.1" will run before "A1" with tag "testOrder.2" and before "A0" with no tags.

Note: all stories, if not having an "testOrder" tag, are considered to be tagged with "testOrderLast" - this should come after any reasonable order tag convention that you might use, like:

  • testOrder.1
  • testOrder
  • testOrder.group1
  • etc

Automatically testing all fiddles

The Guardian will also look for fiddles if this property is set to "true": guardian.settings.fiddles, in the reactor configuration. It will add any sections tagged dfiddle of type story to the list of stories to test.

TODO maybe this particular setting should be automatically set to "true"?

Was this useful?    

By: Razie | 2017-05-01 .. 2022-06-17 | Tags: academy

Viewed 659 times ( | History | Print ) this page.

You need to log in to post a comment!

© Copyright DieselApps, 2012-2024, all rights reserved.