Documenting latest changes

README.md

@@ -122,26 +122,6 @@ The sample scripts in `bin` directory provide examples of how common tasks
 can be achieved using ib-ruby. You may also want to look into `spec/integration`
 directory for more scenarios and examples of handling IB messages.
 
-## RUNNING TESTS:
-
-The gem comes with a spec suit that may be used to test ib-ruby compatibility
-with your specific TWS/Gateway installation. The test suit should be run ONLY
-against your IB paper trading account. Running it against live account may result
-in financial losses.
-
-In order to run tests, you should set up your IB paper trading connection parameters
-in 'spec/spec_helper' file. Modify account_name, host and port under section
-'Your IB PAPER ACCOUNT'. Do not change the client_id.
-
-Before running tests, you need to start your TWS/Gateway and allow API connection.
-You should not have any open/pending orders on your IB paper trading account prior
-to running tests, otherwise some tests will fail. Use 'bin/cancel_orders' script for
-bulk cancelling of open orders before running tests as needed.
-
-You can easily create your own tests following the guide in 'spec/README'.
-Help the development! See 'spec/TODO' for the list of use cases/scenarios
-that still need to be tested.
-
 ## DB BACKEND:
 
 Latest versions of the gem added (optional and experimental) support for data
@@ -168,6 +148,48 @@ you don't need IB::DB.connect part, Rails will take care of it for you. So, just
 Now, all your IB Models are just ActiveRecords and you can do whatever you want with them:
 persist to DB, use in Rails applications, develop controllers and views.
 
+
+## RUNNING TESTS:
+
+The gem comes with a spec suit that may be used to test ib-ruby compatibility
+with your specific TWS/Gateway installation. The test suit should be run ONLY
+against your IB paper trading account. Running it against live account may result
+in financial losses.
+
+In order to run tests, you should set up your IB paper trading connection parameters
+in 'spec/spec_helper' file. Modify account_name, host and port under section
+'Your IB PAPER ACCOUNT'. Do not change the client_id.
+
+Before running tests, you need to start your TWS/Gateway and allow API connection.
+You should not have any open/pending orders on your IB paper trading account prior
+to running tests, otherwise some tests will fail. Use 'bin/cancel_orders' script for
+bulk cancelling of open orders before running tests as needed.
+
+By default, specs are run without database support (tableless). In order to run them
+with database backend, use:
+
+    $ rspec -rdb [spec/specific_spec.rb]
+
+Also, by default, specs suppress logging output that is normally produced by IB::Connection.
+This may make it difficult to debug a failing spec. Following option will switch on verbose
+output (both logger output and content of all received IB messages is dumped). Do not use
+this mode to run a whole spec - you will be swamped! Use it to debug specific failing specs
+only:
+
+    $ rspec -rv [spec/specific_spec.rb]
+
+You can easily create your own tests following the guide in 'spec/README'.
+Help the development! See 'spec/TODO' for the list of use cases/scenarios
+that still need to be tested.
+
+## CONTRIBUTING:
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
 ## LICENSE:
 
 This software is available under the LGPL.

spec/README.md

@@ -1,11 +1,40 @@
-# WRITING INTEGRATION SPECS
+## RUNNING TESTS:
 
-Pattern for writing integration specs is like this:
+The gem comes with a spec suit that may be used to test ib-ruby compatibility
+with your specific TWS/Gateway installation. The test suit should be run ONLY
+against your IB paper trading account. Running it against live account may result
+in financial losses.
 
-1. You define your user scenario (such as: subscribe for FUTURES market data).
+In order to run tests, you should set up your IB paper trading connection parameters
+in 'spec/spec_helper' file. Modify account_name, host and port under section
+'Your IB PAPER ACCOUNT'. Do not change the client_id.
 
-2. You find out experimentally, what messages should be sent to IB to accomplish it,
-   and what messages are sent by IB in return.
+Before running tests, you need to start your TWS/Gateway and allow API connection.
+You should not have any open/pending orders on your IB paper trading account prior
+to running tests, otherwise some tests will fail. Use 'bin/cancel_orders' script for
+bulk cancelling of open orders before running tests as needed.
+
+By default, specs are run without database support (tableless). In order to run them
+with database backend, use:
+
+    $ rspec -rdb [spec/specific_spec.rb]
+
+Also, by default, specs suppress logging output that is normally produced by IB::Connection.
+This may make it difficult to debug a failing spec. Following option will switch on verbose
+output (both logger output and content of all received IB messages is dumped). Do not use
+this mode to run a whole spec - you will be swamped! Use it to debug specific failing specs
+only:
+
+    $ rspec -rv [spec/specific_spec.rb]
+
+# WRITING YOUR OWN INTEGRATION SPECS
+
+You can easily create your own integration specs. Pattern for writing specs is like this:
+
+1. You define your user scenario (such as: subscribe to FUTURES market data).
+
+2. You find out from documentation or experimentally, what messages should be sent to
+   IB to accomplish it, and what messages are sent by IB in return.
 
 3. You start writing spec, requiring 'integration_helper'. Don't forget to
    'verify_account'! Running tests against live IB account can be pretty painful.
@@ -25,24 +54,25 @@ Pattern for writing integration specs is like this:
    @ib.received Hash, keyed by message type. The Hash has following structure:
    {:MessageType1 => [msg1, msg2, msg3...], :MessageType2 => [msg1, msg2, msg3...] }.
 
-7. If you created @ib Connection with mock_logger, all log entries produced by IB
+7. If you created @ib Connection with a mock_logger, all log entries produced by IB
    will be also caught and placed into log_entries Array.
 
-8. Your examples can thus test the content of @ib.received Hash to see what messages
+8. Your examples can thus check the content of @ib.received Hash to see what messages
    were received, or log_entries Array to see what was logged.
 
 9. When done with this context, you call 'close_connection' helper in a top-level
    after(:all) block to get rid of your active connection.
 
 10. If you reuse the connection between contexts and requests, it is recommended to
    call 'clean_connection' in after block to remove old content from @ib.received Hash,
-   or otherwise manually clean it to remove old/not needed messages from it.
+   and log_entries Array or otherwise manually clean them to remove old/not needed
+   messages from and log entries. If your do not do this, your examples become coupled.
 
 11. If you want to see exactly what's going on inside ib-ruby while your examples are
-    running, set OPTS[:silent] = false in your context, and you'll see all the
-    messages received and log entries made as as result of your examples. Be warned,
-    output is very verbose, so don't forget to switch OPTS[:silent] = true after
-    you've done debugging your examples.
+    running, run your specs with '-rv' option to switch on verbose outpset mode.
+    Now you will see all the messages received and log entries made as as result of
+    your examples running. Be warned, output is very verbose, so don't run big chunk of
+    specs with -rv option or you will be swamped!.
 
 Help the development!
 See 'spec/TODO' file for list of scenarios that still need to be tested.