Behavior-Driven Development and the Democratic Process

[domi41]

An analphabet asks revolutionaries writing the first republican constitution : -"How can I compare what you're writing in here to the monarchy I'm being abused by ?" -"Errr... Learn to read ?" -"I trust you ; can you read it to me, pretty please ?" -"Bring forth the trained parrot, comrades."

---

We need a :bird: too ! Something that all can listen to (read, in our N+1).

Gherkin is pretty good at bridging coders with the public at large, being somewhat plain English. Notwithstanding its other benefits.

Feature: Proposing ideas
  In order to share knowledge and initiate legal updates
  As a citizen
  I need to be able to propose ideas

  Background:
    Given I am the citizen named Richard S.
    And there is a tag titled Libre

  Scenario: Propose a fully qualified idea successfully
    When I am on the homepage
    And I trigger the button to propose an idea
    And I fill the title with "Require libre software in all governmental endeavours."
    And I fill the description with "Otherwise, I will draw my katanas." 
    And I add the tag Libre
    And I sign with my keyprint
    And I trigger the button to open the vote
    Then there should be a proposal titled "Require libre software in all governmental endeavours."
    And ...

---

This all raises a serious question : how do we democratically choose the features of the very tool we're using for democracy ?

There's a key point in the lifetime of a project that language creators and IDE designers know well :
When does your language have its own compiler written in it ? At which point do you use your IDE to code your IDE ? What's the name of that key point ? EYODF ?

My point is that it would be easier and make more sense to vote and debate on Steps, Scenarios and whole Features than commits.

Now, I audited rapidly the various prospects one can hope for when rooting for behaviour driven development on Meteor, and Chimp jumped right out of the jungle. There's a lot of poop-throwers using it, seems that it runs quite well with Cucumber (hence, we can Gherkin), and what's more they say we can have a backdoor access to the server database so most of the fixture steps can be taken care of quickly and efficiently. Action steps mostly run in an enslaved client browser, as we manipulate the DOM and simulate end-user keyboard, mouse or touch activity. Check steps can be both client or server, which is very empowering.

Is anyone here experienced with Chimp + Cucumber + Meteor ? Any other runners to suggest ?

It's exciting !

---

A non-telepath asks telepathic revolutionaries working on the legal hivemind : -"How can I compare what you're thinking in here to the mazylegalith I'm being abused by ?" -"Errr... Join the hive ?" -"I trust you. Can you tell me what the hive would answer to these questions ?" -"ASK US ANYTHING."

[santisiri]

This is amazing @domi41. I wasn't aware of Gherkin and cucumber, very interesting stuff.

I will look into Chimp (fun fact, they're part of @piamancini's startup Open Collective so we can reach them at any point in the future).

Something we have pending is that once we have a stable 0.1.0 release, we'll deploy an instance to self.democracy.earth (or a domain similar to that) in order to debate precisely Steps, Scenarios and Features as you mentioned (I only had Features in mind, but makes plenty of sense to me how you're proposing this).

[domi41]

I'm glad you like the concept, and that it's already in your roadmap !

May I suggest meta.democracy.earth as an alternate URL ? It's what Discourse (among others) is using, and it has a nice ring to it.

---

Note that IDEs such as IntellijIDEA handle Gherkin quite well, with linking to step definition, highlighting the variables (this is much more valuable than it seems), warnings on missing steps and step skeletons, the works.

---

I have some experience with regexes and the pitfalls, limitations, and best practices of Gherkin (I painfully know that the Gherkin above can be improved a lot). Do not hesitate to ping me for advice or review.

By the way, did you ever try peer-programming sessions/hackathons through a screen-sharing service Jitsi Meet ? In my experience, features are best discussed by multiple brains and step definitions can oftentimes be written concurrently. You do the Given, I do the Then, let's race ! Multithreading :tada: !

[domi41]

Wrote some top-of-the-head opinionated thoughts about Gherkin.

Feature: Proposing ideas
  In order to share knowledge and initiate legal updates
  As a citizen
  I need to be able to propose ideas

  Background:
    Given I am the citizen named Richard S.
      And there is a tag titled Transparency

  Scenario: Propose a fully qualified idea successfully
        # Sanity checks are optional but good design in early stages
    Given there is no idea titled "Require libre software in all governmental endeavours."
        # Testing other pages should be bug-hunt only and requires shaving the yak to stay dry gherkin-wise.
     When I am on the homepage
        # Now, interacting with the DOM can yield some pretty ugly gherkin, albeit powerful.
      And I click on "#action"
        # Consider this
      And I trigger the action button to propose an idea
        # Or this, maybe?
      And I trigger the floating action button
        # It's more work, so it's okay to use CSS selectors while coding (especially early on)
        # It's also a good way to figure out DOM ids before you even create them.
        # In the long run, features are like code, and should be refactored as well.
        #
        # Check that we're where we should be
     Then I should be on the page to propose an idea
        # Another way to put it
      And I should see the form to propose an idea
        # See how the id `form_propose_an_idea` emerges ?
        #
        # Filling inputs is fine, testing autocompletion is sometimes quirky
     When I fill the title with "Require libre software in all governmental endeavours."
      And I fill the description with "Otherwise, I will draw my katanas."
        # An example of meta-steps that each queue multiple DOM actions
        # Meta steps can be written in Gherkin too ! (not sure Chimp has those)
      And I add the tag Transparency
      And I sign the idea
      And I trigger the button to open the vote
        # Here too we can probably skip CSS selectors if we're clever
      And I submit the idea
        # This can share the same step def as the Given up top.
     Then there should be an idea titled "Require libre software in all governmental endeavours."
      And ...

---

Running multiple concurrent clients to test delegation and such is going to be a challenge !

[bondsbw]

I like this idea, and I have also used Gherkin-style scenarios for testing. I find it a very nice way to explain the precise actions the system is performing, without needing to explain code to non-programmers. And since every line (as opposed to every scenario) generally corresponds to a single function or method, there is no need to understand an entire test in order to reason about the code.

The large number of comments in that example makes sense here given it is intended to explain how it would be used, though I expect in real cases that the Gherkin would be self-explanatory with very few comments.

[domi41]

I have the first Step I am the citizen named Richard S. running green !

Below is the dirty step definition :

    this.Given(/^I am the citizen named (.+)$/, (name) => {
        const slug = convertToSlug(name);

        // Implicitly (but synchronously!) create a citizen
        const user = server.execute((name, slug) => {

            const userData = {
                email: slug+'@test.democracy.earth',
                password: name,
                username: name,
            };

            return Meteor.users.findOne(Accounts.createUser(userData));
        }, name, slug);

        if ( ! user) { // todo: a proper assertion?
            throw new Error("No user was returned after user creation.");
        }

        // Log in as that citizen
        server.call('login', {
            user: {email: slug+'@test.democracy.earth'},
            password: name
        });
    });

I also hooked the AfterScenario event to clear the database and log out.

---

Chimp has ways to go to be as good as Behat :

• console.log is shown without proper indentation and Step scope
• Steps do not have their variables printed in bold
• Blackbox access through DDP is a hack !

[domi41]

Dropping this here, this is an interesting read : https://github.com/xolvio/qualityfaster

[domi41]

We can grab the exports of sovereign in server.execute with require, but it's not very pretty.

    this.Then(/^there should be a tag titled (.+)$/, (title) => {
        const tag = requireServer().execute((title) => {
            Tags = require('/imports/api/tags/Tags').Tags;
            return Tags.findOne({ text: title });
        }, title);

        if ( ! tag) {
            throw new Error(`There is not tag titled '${title}'.`);
        }
    });

If anyone is interested in talking about this, I will be on https://meet.jit.si/sovereign

[santisiri]

Totally agree on using meta.democracy.earth for this (since self is actually taken by our authenticating app, work in progress by @LucasIsasmendi)

[vjrj]

@domi41 I'm using Chimp + Cucumber + Meteor in another project and I'm quite happy. Any problem or question?

[brylie]

@vjrj could you please provide us with an example repository/workflow, so that we can see how it would work?

[vjrj]

It's a local project mainly in Spanish (sorry for that but it's a very specific development for a local political issue): https://github.com/comunes/bebes-robados/tree/master/tests/cucumber/features

This project uses last meteor/chimp versions, but I've started it with old versions of both meteor and chimp and following old documentations and chimp samples.

So maybe it's more recommendable to follow the chimp current documentation and (http://webdriver.io/api.html).

[domi41]

@vjrj Thanks, we do have a question : how to get rid of the browser.pause in the following snippet ?

        // Log in as that citizen on the client
        browser.execute((username, password, done) => {
            console.log("I am printed in the browser's developer console.");
            Meteor.loginWithPassword(username, password, done);
            // note: async/wait does not work in here, no idea why
        }, username, password);

        // There has got to be a better way to wait for meteor login to complete.
        // I tried async/wait, and flavors of the `done` callback. Nothing stuck.
        browser.pause(1000);

Edit : We figured it out ! It was obvious, once we grokked how the whole thing worked :

    getBrowser().timeoutsAsyncScript(2000);
    const returned = getBrowser().executeAsync((email, password, done) => {
      Meteor.loginWithPassword(email, password, (err) => { done(err); });
    }, email, password);

    if (returned && returned.value) {
      fail(`There was an error with the Meteor login : ${returned.value.message}.`);
    }

---

@vjrj Another question, related to your codebase : what's callback ? We cannot find documentation about it.

this.When(/^I enter my name and password$/, function (callback) {
  this.AuthenticationHelper.loginUsername(username, email, passwd);
  callback();
});

---

We have the first six steps passing, and are now working on refactoring to make the step defs as concise and clear as we can. We're also trying to use helpers from the existing tests whenever we can, but we don't know the whole codebase so we might fail hard sometimes.

[domi41]

Chimp out-of-the-box provides the Chai assertion library. There are other assertion libraries out there.

Which one do you prefer ? This is not a choice that should be done without careful consideration, I'm sure @brylie will agree. I'm okay with Chai, overall.

[domi41]

My bad ; the default is Jasmine Expect. After toying around for a while, Chai feels more powerful. It also has a great bunch of extensions.

[domi41]

An update !

We can work with|around the "contenteditable instead of forms" business in the features, which kind of had old habits in despair. Though, for clarity and re-usability we had to rename the ids of the divs that could be edited, from titleContent to ideaTitle and editor to ideaDescription. This way we can generate the ids from the step itself, like "When I fill the idea title with ...". It breaks a lot of things, but shikata ga nai.

The first feature is almost entirely passing (if we don't test tags). If you're still interested by this I'll make a PR once the first feature is green. Not sure if Travis will handle it, though.

[domi41]

There you go, all green ! It's so satisfying to watch Firefox do this at Mach speed. Okay, it's a long test (5s), but it does not feel like it, and there's ways to run only a single Scenario.

$ chimp --chai --ddp=http://localhost:3000

[chimp] Running...
Feature: Proposing ideas

    In order to share knowledge and initiate legal updates
    As a citizen
    I need to be able to propose ideas

  Scenario: Propose a fully qualified idea successfully
  ✔ Given I am the citizen named Richard S.
    | Creating citizen 'Richard S.'…
    | Logging in as 'Richard S.'…
  ✔ And there is a tag titled Transparency
  ✔ And there is a tag titled Sovereignty
  ✔ Given there should not be an idea titled "Require libre software in all governmental endeavours."
  ✔ When I am on the homepage
  ✔ And I trigger the floating action button
  ✔ Then I should be on the page to propose an idea
  ✔ When I set the idea title to "Require libre software in all governmental endeavours."
  ✔ And I set the idea description to "Trusting closed software is a loss of sovereignty."
  ✔ And I add the tag Transparency
  ✔ And I add the tag Sovereignty
  ✔ And I sign the idea
  ✔ And I submit the idea
  ✔ Then there should be an idea titled "Require libre software in all governmental endeavours."

1 scenario (1 passed)
14 steps (14 passed)
0m04.943s

Note that the features branch is based upon the old staging, not master. There's probably going to be conflicts, as we had to change some existing code. We can solve them on our end, but we need your approval @santisiri (specs says we should PR against staging).

---

Now it's time to write some more Gherkin ! Anyone want to try ?

Maybe add a voting ballot to the above idea ?

Then, how about :

Scenario: Vote on someone's idea
Scenario: Vote on my own idea

And then different scenarios for different ballots kinds....

[domi41]

The first scenario of the voting feature is up and about ! it's a simple one, but full of promises. :sunflower: :

Feature: Voting on ideas
  In order to exercise my sovereignty
  As a citizen
  I need to be able to vote on ideas

  Scenario: Receive a thousand votes upon account creation
    Given I am the newly created citizen named N00B
     Then I should have 1000 votes available

Commits will follow suit in PR #198

[domi41]

Two more passing scenarios !

  Scenario: Vote for someone else's idea
    Given I am the citizen named Ali
      And there is a citizen named Bob
      And Bob has proposed a votable idea titled "Bob's Idea"
     Then there should be an idea titled "Bob's Idea"
     When I go to the homepage
     Then I should see "Bob's Idea" in the feed
     When I click on "Bob's Idea" in the feed
     Then I should be on the page /vote/bobs-idea
     #Then I should be on the detail page of the idea titled "Bob's Idea"
     When I click on the Yes ballot option
      And I commit all my votes to the idea
     Then I should have 0 votes available

  Scenario: Vote against someone else's idea
    Given I am the citizen named Ali
      And there is a citizen named Bob
      And Bob has proposed a votable idea titled "Bob's Idea"
     Then there should be an idea titled "Bob's Idea"
     When I go to the homepage
     Then I should see "Bob's Idea" in the feed
     When I click on "Bob's Idea" in the feed
     Then I should be on the page /vote/bobs-idea
     #Then I should be on the detail page of the idea titled "Bob's Idea"
     When I click on the No ballot option
      And I commit all my votes to the idea
     Then I should have 0 votes available

The I commit all my votes to the idea step is quite tricky.

We failed (for hours) to implement the step I commit (\d+) votes to the idea, because trying to move the vote bar handle around does not yield what we expect. Not sure what's responsible for these confusing behaviors, as the webdriver's API regarding the mouse is sketchy at best. They're re-doing everything properly, it'll be ready "when it's ready".

Meanwhile, we're going to keep trying to hack support for this step, as more complex scenarios will require it.

[domi41]

Ok, the step I commit (\d+) votes to the idea is implemented. It's hackish, unreliable, and not a pretty sight, but it's working.

5 scenarios (5 passed)
51 steps (51 passed)
0m18.837s

---

Not sure how to describe the vote delegation, now. Is it even possible from the UI ? We think a normal flow would happen on the would-be delegate public profile page. (like Follow and Unfollow on github). But we're fuzzy on the details ; can we delegate on specific tags ? Can we rescind a delegation ? Can we delegate multiple times on the same tags/categories to the same citizen ? Some of these questions are answered in the open democracy paper (which we read, and loved :heart_eyes:) but the Scenario details (where it happens, and how) are still unclear. Like sound controllers, we would love some input and feedback.

[virgile-dev]

How about we make this a reality. Moving this to next. We've started doing this for the UX enhancement https://github.com/DemocracyEarth/sovereign/issues/238

[domi41]

Closing this with immense fondness for y'all and warmth hope in my heart for a better world. To be continued…