UserStory: As a newcomer to the project, I can get the code running as soon as possible.

[john-arcus]

As a newcomer to the project, I can get the code running as soon as possible.

[john-arcus]

The Quickstart demo should be as easy as Google's Quickstart for the Google Sheets API

Google knows its stuff. So, to use the structure of Google's page as a benchmark:

• Quickstart - Intro. Promise to get the reader up and running in about 5 minutes.
• Prerequisites - We should have Composer, plus Vagrant so we can harness Homestead Improved to create the environment. Then, PHP and MySql will already be inside the Vagrant Homestead Vm.
• Steps:
  • Clone the project
  • Fire up Homestead Vagrant
  • SSH'in
  • Run the quickstart.php script. Which should:
    • Ensure the db is set up, create table
    • Populate a table with domain objects
    • Find a collection of domain objects
    • Write out their names to STDOUT .
    • End script.

[john-arcus]

Let's rewrite this as a Behat spec. in the form of:

Feature: Some terse yet descriptive text of what is desired
  In order to realize a named business value
  As an explicit system actor
  I want to gain some beneficial outcome which furthers the goal

  Additional text...

  Scenario: Some determinable business situation
    Given some precondition
    And some other precondition
    When some action by the actor
    And some other action
    And yet another action
    Then some testable outcome is achieved
    And something else we can check happens too

  Scenario: A different situation
    ...

and save it into the project at:

features/quickstart.feature

[john-arcus]

Create the file and folder:

Johns-MBP:xandria-demo jw$ pwd
/Users/jw/Documents/Projects/PackageDev/xandria-demo
Johns-MBP:xandria-demo jw$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
Johns-MBP:xandria-demo jw$ mkdir features
Johns-MBP:xandria-demo jw$ touch features/quickstart.feature

[john-arcus]

I have written some content for the Behat feature. (I am not sure how easy it is to test these automatically).

[john-arcus]

I have just read an article by Dan North about what makes a good User Story.

My current feature is probably not one story but three.

I also noticed that this article has a mistake in it:

Apparently this ATM gives you $10 every time you try to take $20 out whilst having insufficient funds. :) ...

See:

The characteristics of a good story

Scenario 2: Account has insufficient funds
Given the account balance is \$10
 And the card is valid
 And the machine contains enough money
When the Account Holder requests \$20
Then the ATM should not dispense any money
 And the ATM should say there are insufficient funds
 And the account balance should be \$20
 And the card should be returned

~I cannot add a comment to correct that article. So, hopefully anyone reading this could let him know somehow~.

I sent a message to Dan and received a prompt response. The error was in there because, in the original text, it is used to convey that bugs can appear in stories as well as in code. So, it is OK.

[john-arcus]

Let's continue with the Behat process. I am following the Quickstart page on the Behat site.

Run the installation of Behat.

# composer require --dev behat/behat

check the installed version:

# vendor/bin/behat -V
behat 3.4.3

[john-arcus]

Now configure the Behat test suite using the default suite.

# pwd
/Users/jw/Documents/Projects/PackageDev/xandria-demo
# vendor/bin/behat --init
+d features/bootstrap - place your context classes here
+f features/bootstrap/FeatureContext.php - place your definitions, transformations and hooks here

Check it out.

# ls -lah features/bootstrap/
total 8
drwxr-xr-x  3 jw  staff    96B 18 Apr 16:01 .
drwxr-xr-x  4 jw  staff   128B 18 Apr 16:01 ..
-rw-r--r--  1 jw  staff   471B 18 Apr 16:01 FeatureContext.php

[john-arcus]

so, let's run Behat and see what happens

$ vendor/bin/behat
Feature: Quick Start to see demo in action.
  In order to encourage speedy use and understanding of the Xandria library
  As a PHP developer who is new to the project
  I can see the demo code working with least amount of effort on my part.

  It is a common courtesy to make it easy for newcomers. Any project that exposes the ethos that they value contributors
  and make the effort to welcome them will get more supporters.

  Scenario: Cloning the Xandria-Demo project.                     # features/quickstart.feature:9
    Given I have access to the "project's github repo"
    When I visit "the README file"
    Then I can see "instructions on how to clone the repository".

  Scenario: Launching the environment.                                               # features/quickstart.feature:14
    Given I have cloned the project locally
    And I have "Vagrant" and a "virtualization product" installed on my host machine
    When I navigate to the "project's root directory" in my terminal
    And run `vagrant up`
    Then vagrant provisions "Homestead Improved virtual environment"
    And launches it

  Scenario: Run the demo code to prove it works.                                                  # features/quickstart.feature:22
    Given I have navigated to "the project's root directory" in my terminal
    And I have the project's "Homestead Improved virtual environment" running.
    And I have run vagrant ssh
    When I run the command to run the project's "quickstart.php" script
    Then The "expected output" is written to STDOUT to prove that the project code is working OK.

3 scenarios (3 undefined)
14 steps (14 undefined)
0m0.01s (7.08Mb)

 >> default suite has undefined steps. Please choose the context to generate snippets:

  [0] None
  [1] FeatureContext
 > 

[john-arcus]

As per the Defining Steps section of the tutorial, let's get Behat to write my test code snippets for me:

$ vendor/bin/behat --dry-run --append-snippets

Done.

[john-arcus]

Now run it again

Johns-MBP:xandria-demo jw$ vendor/bin/behat
Feature: Quick Start to see demo in action.
  In order to encourage speedy use and understanding of the Xandria library
  As a PHP developer who is new to the project
  I can see the demo code working with least amount of effort on my part.

  It is a common courtesy to make it easy for newcomers. Any project that exposes the ethos that they value contributors
  and make the effort to welcome them will get more supporters.

  Scenario: Cloning the Xandria-Demo project.                     # features/quickstart.feature:9
    Given I have access to the "project's github repo"            # FeatureContext::iHaveAccessToThe()
      TODO: write pending definition
    When I visit "the README file"                                # FeatureContext::iVisit()
    Then I can see "instructions on how to clone the repository". # FeatureContext::iCanSee()

  Scenario: Launching the environment.                                               # features/quickstart.feature:14
    Given I have cloned the project locally                                          # FeatureContext::iHaveClonedTheProjectLocally()
      TODO: write pending definition
    And I have "Vagrant" and a "virtualization product" installed on my host machine # FeatureContext::iHaveAndAInstalledOnMyHostMachine()
    When I navigate to the "project's root directory" in my terminal                 # FeatureContext::iNavigateToTheInMyTerminal()
    And run `vagrant up`                                                             # FeatureContext::runVagrantUp()
    Then vagrant provisions "Homestead Improved virtual environment"                 # FeatureContext::vagrantProvisions()
    And launches it                                                                  # FeatureContext::launchesIt()

  Scenario: Run the demo code to prove it works.                                                  # features/quickstart.feature:22
    Given I have navigated to "the project's root directory" in my terminal                       # FeatureContext::iHaveNavigatedToInMyTerminal()
      TODO: write pending definition
    And I have the project's "Homestead Improved virtual environment" running.                    # FeatureContext::iHaveTheProjectsRunning()
    And I have run vagrant ssh                                                                    # FeatureContext::iHaveRunVagrantSsh()
    When I run the command to run the project's "quickstart.php" script                           # FeatureContext::iRunTheCommandToRunTheProjectsScript()
    Then The "expected output" is written to STDOUT to prove that the project code is working OK. # FeatureContext::theIsWrittenToStdoutToProveThatTheProjectCodeIsWorkingOk()

3 scenarios (3 pending)
14 steps (3 pending, 11 skipped)
0m0.01s (7.16Mb)
Johns-MBP:xandria-demo jw$

[john-arcus]

OK. So the test methods are written but each one is throwing a Pending Exception which, I guess is warning us that the body has not been written yet.

[john-arcus]

Next let's start automating Behat steps.

Behat doesn’t come with its own assertion tool, but you can use any proper assertion tool out there. A proper assertion tool is a library whose assertions throw exceptions on failure. For example, if you’re familiar with PHPUnit you can use its assertions in Behat by installing it via composer:

$ php composer.phar require --dev phpunit/phpunit

So, run that and get some PHPUnit into my life.

$ composer require --dev phpunit/phpunit

Done.

[john-arcus]

I am back on this. I have struggled to understand how to use Behat to test certain standards for project best practices and realise that it was because I was trying to test something that was above the project in the dependency hierarchy. So, the project and hence the Behat tests should not be knowing about it.

ie. Although we can assert that the project should have a README file which contains xyz. We cannot assert that the project knows which is its home on github.

However, there may be a way of asserting the existence of project badges which may indicate certain standards. I shall look into this sometime.

[john-arcus]

I have removed the behat scenario about cloning the project as it is too much meta project knowledge.

Let's wipe the context file and get behat to recreate it:

$ pwd
 /Users/jw/Documents/Projects/PackageDev/xandria-demo
$ vendor/bin/behat --init
+f features/bootstrap/FeatureContext.php - place your definitions, transformations and hooks here

$ vendor/bin/behat --dry-run --append-snippets
Feature: Quick Start to see demo in action.
  In order to encourage speedy use and understanding of the Xandria library
  As a PHP developer who is new to the project
  I can see the demo code working with least amount of effort on my part.

  It is a common courtesy to make it easy for newcomers. Any project that exposes the ethos that they value contributors
  and make the effort to welcome them will get more supporters.

  Scenario: Launching the environment.                                               # features/quickstart.feature:10
    Given I have cloned the project locally
    And I have "Vagrant" and a "virtualization product" installed on my host machine
    When I navigate to the "project's root directory" in my terminal
    And run `vagrant up`
    Then vagrant provisions "Homestead Improved virtual environment"
    And launches it

  Scenario: Run the demo code to prove it works.                                                  # features/quickstart.feature:18
    Given I have navigated to "the project's root directory" in my terminal
    And I have the project's "Homestead Improved virtual environment" running.
    And I have run vagrant ssh
    When I run the command to run the project's "quickstart.php" script
    Then The "expected output" is written to STDOUT to prove that the project code is working OK.

2 scenarios (2 undefined)
11 steps (11 undefined)
0m0.03s (7.12Mb)

 >> default suite has undefined steps. Please choose the context to generate snippets:

  [0] None
  [1] FeatureContext
 > 1

u features/bootstrap/FeatureContext.php - `I have cloned the project locally` definition added
u features/bootstrap/FeatureContext.php - `I have "Vagrant" and a "virtualization product" installed on my host machine` definition added
u features/bootstrap/FeatureContext.php - `I navigate to the "project's root directory" in my terminal` definition added
u features/bootstrap/FeatureContext.php - `run `vagrant up`` definition added
u features/bootstrap/FeatureContext.php - `vagrant provisions "Homestead Improved virtual environment"` definition added
u features/bootstrap/FeatureContext.php - `launches it` definition added
u features/bootstrap/FeatureContext.php - `I have navigated to "the project's root directory" in my terminal` definition added
u features/bootstrap/FeatureContext.php - `I have the project's "Homestead Improved virtual environment" running.` definition added
u features/bootstrap/FeatureContext.php - `I have run vagrant ssh` definition added
u features/bootstrap/FeatureContext.php - `I run the command to run the project's "quickstart.php" script` definition added
u features/bootstrap/FeatureContext.php - `The "expected output" is written to STDOUT to prove that the project code is working OK.` definition added

[john-arcus]

I have pruned the Scenarios down some more to simplify them. Deleted the FeatureContext.php file ad got Behat to recreate it using.

$ vendor/bin/behat --init
$ vendor/bin/behat --dry-run --append-snippets

[john-arcus]

Ok let's run Behat to see what we need to do to make the Scenarios pass:

$ vendor/bin/behat 
Feature: Quick Start to see demo in action.
  In order to encourage speedy use and understanding of the Xandria library
  As a PHP developer who is new to the project
  I can see the demo code working with least amount of effort on my part.

  It is a common courtesy to make it easy for newcomers. Any project that exposes the ethos that they value contributors
  and make the effort to welcome them will get more supporters.

  Scenario: Launching the environment.                                            # features/quickstart.feature:10
    Given I have installed the project                                            # FeatureContext::iHaveInstalledTheProject()
      TODO: write pending definition
    And I have Vagrant and a virtualization product installed on my host machine  # FeatureContext::iHaveVagrantAndAVirtualizationProductInstalledOnMyHostMachine()
    When I run `vagrant up` in the root of the project                            # FeatureContext::iRunVagrantUpInTheRootOfTheProject()
    Then vagrant provisions and launches a Homestead Improved virtual environment # FeatureContext::vagrantProvisionsAndLaunchesAHomesteadImprovedVirtualEnvironment()

  Scenario: Run the demo code to prove it works.                                                # features/quickstart.feature:16
    Given I have installed the project                                                          # FeatureContext::iHaveInstalledTheProject()
      TODO: write pending definition
    When I run the command to run the project's quickstart.php script                           # FeatureContext::iRunTheCommandToRunTheProjectsQuickstartPhpScript()
    Then The expected output is written to STDOUT to prove that the project code is working OK. # FeatureContext::theExpectedOutputIsWrittenToStdoutToProveThatTheProjectCodeIsWorkingOk()

2 scenarios (2 pending)
7 steps (2 pending, 5 skipped)
0m0.01s (7.31Mb)

[john-arcus]

Homestead as a Per Project installation

I have been looking at Homestead Improved and trying to work out how to make use of it as part of this project. However, I am starting to think that Homestead Improved is not designed to be used in other packages.

Homestead, it seems, does have instructions on Per Project installation.

I have also found an article about Per Project installations of Homestead.

I have skimmed though it, but will go through it in detail tomoz. It looks like that no matter which way it is done, a user is still going to have to do some configuration of Homestead to make it run on their own machine. They cannot just clone our project repo and run vagrant up.

[john-arcus]

As I wrote the comment above, I might do some kind of half-way house and see if I can borrow a lot from Homestead Improved and just make the Homestead.yaml into a Homestead.yaml.example file before committing. I shall sleep on it.

[john-arcus]

I need to read up about Laravel Homestead to see if I can use it in favour of Homestead Improved.

Ensure:

• Db is created
• ssh keys are made simple
• Can be added on a Per Project basis
  • With instructions for collaborators on how to get to the point of vagrant up on a cloned copy

[john-arcus]

I have tried to find some documentation for the Laravel Homestead yaml but could not find any. I did find this article which was quite good although it still doesn’t appear to cover each key in the yaml.