Run To The Future

The Goal Driven Design (GDD) process for designing the interface comes from the excellent Cooper design firm.

This is a summary of what we use from GDD as part of our design process.

UX = user experience, which is more than just how the website looks (in fact, how it looks is secondary), it's about how the user will interact with the website to get done whatever it is they want to do

1. Identify the primary persona
   
   The primary persona is a fictional archetype that represents the main users of the site. So you might fill in the following for your primary persona:
   
   

   Name:

   Age:

   Sex:

   Occupation:

   Interests:

   Web experience:

   Similar site experience:

   Domain experience:

   
   There is only one primary persona.
   
   
2. Identify the goals of the primary persona
   
   What does the primary persona actually want to get out of using the site?
   
   Three types of goals:
   

   End goals	what they want to get out of the site – the most important goals
   Experience goals	how they want to feel when using the site
   Life goals

3. Problem and vision statements
4. Context scenario
   
   A short story of the primary persona using the site to achieve their goals
   
   
5. Functional and data requirements
   
   These are the nouns and verbs of your site in terms that the user would use. That is, the things on the site, and what the user can do with them.
   
   
6. Functional groups and hierarchy
   
   Can the data requirements be grouped logically, if so how?
   
   
7. Sketches
   
   Very rough layout sketches of different pages on the site (using the data and functional requirements)
   
   
8. Key path scenarios
   
   These are story boards of the primary persona going to each page using the sketches to show the steps a user needs to take to achieve their goal.
   
   

After that we do prototypes.

Install instructions:
rails new myapp --skip-test-unit --skip-active-record

See http://www.rubyinside.com/how-to-rails-3-and-rspec-2-4336.html and http://www.mongodb.org/display/DOCS/Rails+3+-+Getting+Started.

Lithium Acceptance Tests using Cucumber and Webrat

Introduction

Cucumber (aka. cuke) and webrat are ruby tools for behaviour driven development (BDD) and while they're mostly used on rails apps, they can be applied to PHP apps too. Our motivation for doing this comes from using a virtual machine (vm) for our (work) development. We're using lithium now for all new projects, and we want to do BDD and Test Driven Development (TDD) as well. TDD is fine – lithium supports this really well out of the box (and michaeltwofish is currently writing a lithium plugin to allow the command line testing to output to hudson). Our plan was to use selenium for the acceptance tests (read BDD), but as selenium needs to run a firefox executable, this can't work (easily¹) on the vm. So we've now got webrat (and cuke) running instead.

Most of this post is taken from other sources. The first place to read is aslakhellesoy/cucumber/wiki/php. It's also well worth looking at chits: a real PHP application that uses cucumber/webrat. Also see Acceptance tests on a PHP project with the cucumber / webrat / selenium trio.

I repeated these procedures on darwin and centOS without any problems.

Installing ruby and gems

I downloaded and installed ruby 1.9.2 from source. This also installed the latest version of ruby gems.

$ ruby -v
ruby 1.9.2p0 (2010-08-18 revision 29036) [x86_64-darwin10.5.0]
$ gem -v
1.3.7

Installing required gems (cucumber and webrat)

These are the gems I installed:

$ gem install cucumber
$ gem install webrat
$ gem install mechanize
$ gem install rspec

Layout

You'll need to put your cuke and webrat files somewhere. Typical location is the app/tests/features directory. The feature files go in the top "features" directory:

+––– apps/tests/features/
     +–––feature1.feature
     +–––feature2.feature
     +––– step_definitions/
           +–––webrat_steps.rb
     +–––support/
           +–––env.rb
           +–––hooks.rb
           +–––paths.rb

Features

A feature could map to a high level user story (in the agile method), and be made up of a number of scenarios to be tested. The feature is executed by cucumber and the output will show whether your acceptance tests have passed or failed (or some other error has occurred).

There's plenty of information about how to write these feature files on the cucumber site.

Step Definitions

Each step of a scenario (within the feature file) needs a definition in code of what is to be executed. These steps go in the step_definitions/webrat_steps.rb file. Some of the steps defined here are "standard" eg:

Then /^I should see "(.*)"$/ do |text|
  assert !!(response_body =~ /#{Regexp.escape text}/m), response_body
end

which is used to check if a particular piece of text appears on the page.

See the webrat repo on github, as well as the cucumber wiki page on step definitions, but also take a look at the step definitions of the chits app as this has a lot more examples.²

Support Files

There are three support files. env.rb is used to setup the testing and code here is run before (and possibly after) every scenario. The paths.rb file is a convenient place for the URLs webrat will access. The hooks.rb isn't strictly necessary but if there is code that needs to run before (or after) specific scenarios, this is where it goes.

See the wiki page on using cucumber for PHP apps and the chits support files for examples.

Conclusion

In Part 2 I will talk about getting this to work on a lithium application, in Part 3 I will talk about using cucumber to drive selenium tests and in Part 4 I will talk about putting it under continuous integration with Hudson.

1. All we really need is a headless firefox executable for linux. There is one, we just haven't installed it on our vm yet. But the other big benefit of using webrat over selenium is that it has a much lighter resource footprint. ↩
2. Please note that the first line of this file (from the chits app on github) uses "re". I'm not sure if this is a ruby thing, but I had to change it to "require" to get it to work:

   require File.expand_path(File.join(File.dirname(__FILE__), "..", "support", "paths" ↩

These instructions are to show how to create a new git repo for a new application called myapp.

1. Get git on the central repo

The test location for git repos is /usr/gitroot on the test machine.
Go to /usr/gitroot and run the following:
sudo mkdir myapp.git
cd myapp.git
sudo git init --bare --shared=all

Now a new empty git repo has been created.

2. Copy existing application

Assuming on your local machine you've already created the skeleton for myapp
Go into the myapp directory and run the following:
git init
git add .
git commit
You will need to write a commit message such as "initial project check in".
This will have created the master branch.
Then push myapp to the central repo:
git push ssh://test/usr/gitroot/myapp.git '\*:\*'

3. Remove existing repo and check out central repo

The easiest thing to do now is delete the skeleton app you created and check out the app from the central repo:
cd ..
rm -rf myapp
git clone ssh://test/usr/gitroot/myapp.git myapp

4. Configure your app for git

I have a global git config (for connection to lithium) so I create a git config for the app:
cd myapp
vim .git/config
And I add:
[user]
name = rttf
email = rttf@test.com
You might want to add other configuration options.
You have to set this yourself – it's not part of the repo.

5. Create a dev branch

Depending on your application you will want to create a dev branch (dev branch is the working branch, master is the release branch):
git checkout -b dev
This will create and checkout the dev branch.
You can check which branch you're on with:
git branch
Or checkout the remote branches with:
git branch -r
Then push your new branch to the central repo:
git push origin dev

6. Using an existing application

If you're joining an ongoing project and you need to checkout an existing repo, use:
git checkout --track -b dev origin/dev
This assumes the main work is being done on the dev branch.
When updating your code you shouldn't use git pull. User git fetch first, then git merge. [This article|http://longair.net/blog/2009/04/16/git-fetch-and-merge/] explains why not to use git pull.

Including a submodule

Which we want to do for libraries/plugins.
For example, to add the core library, from the app directory:
git submodule add ssh://@test/usr/gitroot/core.git libraries/core
git submodule init
git submodule update
Also make sure the url in the newly created .gitmodules file doesn't have your in it.
Then commit and push any changes.

Updating submodule code

Submodules are included as a detached head. To make a change to submodule, checkout the relevant branch first, eg:
git checkout master
Then push these changes to origin.

Updating a submodule from within the parent application

From the parent application you need to add and commit (and then push to origin) the changed submodule (in other words, the fact that the submodule has changed).

Tagging

To view all tags:
git tag
To view a tag's details:
git show
To create a tag:
git tag -a For which you'll have to add a comment.
Push tags to origin:
git push --tags origin master (Normally we would only create tags on the master (release) branch.)
To update to a tag (normally from where you are deploying, stage, test or live):
git checkout

Useful commands

git describe --always --tag
git log -1 --format="%H%n%aD"

I'm always forgetting this. Yes, a quick google search reveals it, but I'd rather put it here as well:

gem install --http-proxy http://proxy:3128 rails