Summary: 

This sets up cucumber and capybara to test sites through apache.  It was specifically written for php but can be used for any framework.

Steps:

- Install the following gems: cucumber mechanize rspec capybara capybara-mechanize mysql2
- If using selenium testing on a headless box, install xvfb and firefox
- setup virthost for the test site
  - sample virthost:
  <VirtualHost *:80>
      DocumentRoot "/srv/yoursitehere_test/public"
      ServerName test.yoursitehere.com
      ServerAlias test.yoursitehere.com
      ErrorLog "/private/var/log/apache2/local.yoursitehere_test.com-error_log"
      CustomLog "/private/var/log/apache2/local.yoursitehere_test.com-access_log" common
  </VirtualHost>
- copy the public folder to your php public or public_html folder
  - make sure the htaccess gets copied as well to stop access to the tests from the browser
  - if your project already has a rakefile, merge the two rakefiles
- add a schema dump to features/support/db_schemas
- setup database connections file
  - name: the database name
  - location: database server
  - schema: schema file, automatically looks at features/support/db_schemas
  - user: mysql user
  - password: mysql user password
  - admin_user: mysql administrator user to override the default in env.rb
  - admin_password: mysql administrator password to override the default in env.rb
  - var_name: variable name used in the conn.php file as the result of mysql_select_db
  - default: set to true or false; the one set to true is the default database
- Setup the support/env.rb file
  - set capybara app and app_host
  - set default mysql admin user and password
  - set the database_config_path
    - any functions or additional database connections in your connection file should be duplicated when the file is rewritten for testing
    - if the backup_database_config_file is set, it will create a new file with your connection information in the current directory
  - if the database should not be reseeded before every test, remove the database drop and create, and uncomment the database reset in the rollback_to_seed_data function
- setup support/paths.rb
  - change the base path location from test.yoursitehere to your site name in the virthost
- setup step_definitions/web_steps.rb
  - look at the alternative version of the 'should be on' step that is used for absolute links
  - if an updated set of generic capybara steps are needed, this step will need to be changed

Additional notes:

- setting the database to test
  - when launched, the script will read the database connection file, store it, and overwrite it with test data
  - when tests are complete, the original database connection file will be restored
  - if cucumber crashes or is killed, you may lose your database connectio information.
  - there is currently no check to make sure the correct database connection file is in place before or after a test
- If you want to prep or reset a table after a test, use the support/hooks.rb file.  
  - note that it writes to the /tmp directory
- there is a 'path "(^")"' step in support/paths that will direct link to a path
  - other paths can be created as normal if you want to name your pages
- selenium tests are supported by adding a @javascript tag
- the admin user needs a -u and -p before their login credentials, the test database user does not
  - this avoids extra password requests when mysql is given an empty -p argument

Future work:

- a more intelligent restoration of the database connection file is needed
  - if cucumber crashes or is killed, the at_exit does not necessarily run
  - a series of backups needs to be managed and used to restore the connection file
  - an additional task rake cucumber:cleanup should remove the test databases, and restore the connection file from the most recent backup
- automatic database schema generation
  - add a system for storing information for the current development/production database
  - if it exists and the currently dumped schema is old, dump the schema into the schemas folder and use it for the next test
  - manage schemas to avoid generating too many
- add a cucumber.yml with a profile so standard cucumber rake tasks can be used
- change the location parameter in database.yml to host
- look at file upload tests: http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions#attach_file-instance_method