Merge pull request hanami#406 from moonglum/getting-started-improvements

Improvements to the Getting Started guide
Advanon · Nov 6, 2017 · 7030571 · 7030571
2 parents c51d728 + f78bc22
commit 7030571
Show file tree

Hide file tree

Showing 2 changed files with 58 additions and 58 deletions.
diff --git a/source/guides/1.0/getting-started.md b/source/guides/1.0/getting-started.md
@@ -177,7 +177,7 @@ As you can see, we have set `HANAMI_ENV` environment variable to instruct our co
 Now we have a test, we can see it fail:
 
 ```
-% rake test
+% bundle exec rake test
 Run options: --seed 44759
 
 # Running:
@@ -319,7 +319,7 @@ To make our test pass, we need to edit our newly generated template file in `app
 </div>
 ```
 
-Save your changes and see your tests pass!
+Save your changes and see your tests pass! The output will also contain a skipped test. This is due to an autogenerated test in `spec/web/views/books/index_spec.rb`.
 
 The terminology of controllers and actions might be confusing, so let's clear this up: actions form the basis of our Hanami applications; controllers are mere modules that group several actions together.
 So while the "controller" is _conceptually_ present in our project, in practice we only deal with actions.
@@ -347,7 +347,11 @@ Open up the file `apps/web/templates/application.html.erb` and edit it to look l
 </html>
 ```
 
-Now you can remove the duplicate lines from the other templates.
+Now you can remove the duplicate lines from the other templates. Let's run the tests again to check that everything worked fine:
+
+```
+bundle exec rake test
+```
 
 A **layout** is like any other template, but it is used to wrap your regular templates.
 The `yield` line is replaced with the contents of our regular template.
@@ -386,7 +390,7 @@ The generator gives us an entity, a repository, a migration, and accompanying te
 
 ### Migrations To Change Our Database Schema
 
-Let's modify the generated migration to include `title` and `author` fields:
+Let's modify the generated migration (the path to the migration will differ for you, because it contains a timestamp) to include `title` and `author` fields:
 
 ```ruby
 # db/migrations/20161115110038_create_books.rb
@@ -422,7 +426,7 @@ Let's prepare our database for the development and test environments:
 An entity is something really close to a plain Ruby object.
 We should focus on the behaviors that we want from it and only then, how to save it.
 
-For now, we need to create simple entity class:
+For now, we keep the generated entity class:
 
 ```ruby
 # lib/bookshelf/entities/book.rb
@@ -435,7 +439,7 @@ We can verify it all works as expected with a unit test:
 
 ```ruby
 # spec/bookshelf/entities/book_spec.rb
-require 'spec_helper'
+require_relative '../../spec_helper'
 
 describe Book do
   it 'can be initialized with attributes' do
@@ -506,8 +510,7 @@ Let's write a test to force this change in our view:
 
 ```ruby
 # spec/web/views/books/index_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/views/books/index'
+require_relative '../../../spec_helper'
 
 describe Web::Views::Books::Index do
   let(:exposures) { Hash[books: []] }
@@ -573,8 +576,7 @@ that change:
 
 ```ruby
 # spec/web/controllers/books/index_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/controllers/books/index'
+require_relative '../../../spec_helper'
 
 describe Web::Controllers::Books::Index do
   let(:action) { Web::Controllers::Books::Index.new }
@@ -630,7 +632,7 @@ Run options: --seed 59133
 
 Finished in 0.042065s, 213.9543 runs/s, 380.3633 assertions/s.
 
-6 runs, 7 assertions, 0 failures, 0 errors, 0 skips
+9 runs, 16 assertions, 0 failures, 0 errors, 0 skips
 ```
 
 ## Building Forms To Create Records
@@ -739,8 +741,7 @@ Let's express them as unit tests:
 
 ```ruby
 # spec/web/controllers/books/create_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/controllers/books/create'
+require_relative '../../../spec_helper'
 
 describe Web::Controllers::Books::Create do
   let(:action) { Web::Controllers::Books::Create.new }
@@ -768,7 +769,7 @@ describe Web::Controllers::Books::Create do
 end
 ```
 
-Making these tests pass is easy enough.
+Let's make these tests pass!
 We've already seen how we can write entities to our database, and we can use `redirect_to` to implement our redirection:
 
 ```ruby
@@ -794,11 +795,13 @@ Run options: --seed 63592
 
 # Running:
 
-...............
+...S.S.........
 
 Finished in 0.081961s, 183.0142 runs/s, 305.0236 assertions/s.
 
-12 runs, 14 assertions, 0 failures, 0 errors, 2 skips
+15 runs, 23 assertions, 0 failures, 0 errors, 2 skips
+
+You have skipped tests. Run with --verbose for details.
 ```
 
 Congratulations!
@@ -817,8 +820,7 @@ Let's specify this behaviour as unit tests:
 
 ```ruby
 # spec/web/controllers/books/create_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/controllers/books/create'
+require_relative '../../../spec_helper'
 
 describe Web::Controllers::Books::Create do
   let(:action) { Web::Controllers::Books::Create.new }
@@ -935,9 +937,7 @@ First, we expect a list of errors to be included in the page when `params` conta
 
 ```ruby
 # spec/web/views/books/new_spec.rb
-require 'spec_helper'
-require 'ostruct'
-require_relative '../../../../apps/web/views/books/new'
+require_relative '../../../spec_helper'
 
 describe Web::Views::Books::New do
   let(:params)    { OpenStruct.new(valid?: false, error_messages: ['Title must be filled', 'Author must be filled']) }
@@ -980,7 +980,7 @@ end
 ```
 
 In our template we can loop over `params.errors` (if there are any) and display a friendly message.
-Open up `apps/web/templates/books/new.html.erb`:
+Open up `apps/web/templates/books/new.html.erb` and add the following at the top of the file:
 
 ```erb
 <% unless params.valid? %>
@@ -1003,11 +1003,13 @@ Run options: --seed 59940
 
 # Running:
 
-..................
+......S..........
+
+Finished in 0.188950s, 89.9707 runs/s, 179.9413 assertions/s.
 
-Finished in 0.078112s, 230.4372 runs/s, 473.6765 assertions/s.
+17 runs, 34 assertions, 0 failures, 0 errors, 1 skips
 
-15 runs, 27 assertions, 0 failures, 0 errors, 1 skips
+You have skipped tests. Run with --verbose for details.
 ```
 
 ### Improving Our Use Of The Router
@@ -1031,7 +1033,7 @@ resources :books, only: [:index, :new, :create]
 ```
 
 To get a sense of what routes are defined, now we've made this change, you can
-use the special command-line task `routes` to inspect the end result:
+run `bundle exec hanami routes` on your command-line to inspect the end result:
 
 ```
 % bundle exec hanami routes
@@ -1043,10 +1045,10 @@ use the special command-line task `routes` to inspect the end result:
     books POST       /books                         Web::Controllers::Books::Create
 ```
 
-The output for `hanami routes` shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.
+The output shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.
 
 Now we've applied the `resources` helper method, we can take advantage of the named route methods.
-Remember how we built our form using `form_for`?
+Remember how we built our form using `form_for` in `apps/web/templates/books/new.html.erb`?
 
 ```erb
 <%=
@@ -1056,7 +1058,7 @@ Remember how we built our form using `form_for`?
 %>
 ```
 
-It's silly to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
+We don't need to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
 We can use the `routes` helper method that is available in our views and actions to access route-specific helper methods:
 
 ```erb

diff --git a/source/guides/1.1/getting-started.md b/source/guides/1.1/getting-started.md
@@ -177,7 +177,7 @@ As you can see, we have set `HANAMI_ENV` environment variable to instruct our co
 Now we have a test, we can see it fail:
 
 ```
-% rake test
+% bundle exec rake test
 Run options: --seed 44759
 
 # Running:
@@ -319,7 +319,7 @@ To make our test pass, we need to edit our newly generated template file in `app
 </div>
 ```
 
-Save your changes and see your tests pass!
+Save your changes and see your tests pass! The output will also contain a skipped test. This is due to an autogenerated test in `spec/web/views/books/index_spec.rb`.
 
 The terminology of controllers and actions might be confusing, so let's clear this up: actions form the basis of our Hanami applications; controllers are mere modules that group several actions together.
 So while the "controller" is _conceptually_ present in our project, in practice we only deal with actions.
@@ -347,7 +347,7 @@ Open up the file `apps/web/templates/application.html.erb` and edit it to look l
 </html>
 ```
 
-Now you can remove the duplicate lines from the other templates.
+Now you can remove the duplicate lines from the other templates. Let's run the tests again to check that everything worked fine.
 
 A **layout** is like any other template, but it is used to wrap your regular templates.
 The `yield` line is replaced with the contents of our regular template.
@@ -386,7 +386,7 @@ The generator gives us an entity, a repository, a migration, and accompanying te
 
 ### Migrations To Change Our Database Schema
 
-Let's modify the generated migration to include `title` and `author` fields:
+Let's modify the generated migration (the path to the migration will differ for you, because it contains a timestamp) to include `title` and `author` fields:
 
 ```ruby
 # db/migrations/20161115110038_create_books.rb
@@ -422,7 +422,7 @@ Let's prepare our database for the development and test environments:
 An entity is something really close to a plain Ruby object.
 We should focus on the behaviors that we want from it and only then, how to save it.
 
-For now, we need to create simple entity class:
+For now, we keep the generated entity class:
 
 ```ruby
 # lib/bookshelf/entities/book.rb
@@ -435,7 +435,7 @@ We can verify it all works as expected with a unit test:
 
 ```ruby
 # spec/bookshelf/entities/book_spec.rb
-require 'spec_helper'
+require_relative '../../spec_helper'
 
 describe Book do
   it 'can be initialized with attributes' do
@@ -506,8 +506,7 @@ Let's write a test to force this change in our view:
 
 ```ruby
 # spec/web/views/books/index_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/views/books/index'
+require_relative '../../../spec_helper'
 
 describe Web::Views::Books::Index do
   let(:exposures) { Hash[books: []] }
@@ -573,8 +572,7 @@ that change:
 
 ```ruby
 # spec/web/controllers/books/index_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/controllers/books/index'
+require_relative '../../../spec_helper'
 
 describe Web::Controllers::Books::Index do
   let(:action) { Web::Controllers::Books::Index.new }
@@ -630,7 +628,7 @@ Run options: --seed 59133
 
 Finished in 0.042065s, 213.9543 runs/s, 380.3633 assertions/s.
 
-6 runs, 7 assertions, 0 failures, 0 errors, 0 skips
+9 runs, 16 assertions, 0 failures, 0 errors, 0 skips
 ```
 
 ## Building Forms To Create Records
@@ -739,8 +737,7 @@ Let's express them as unit tests:
 
 ```ruby
 # spec/web/controllers/books/create_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/controllers/books/create'
+require_relative '../../../spec_helper'
 
 describe Web::Controllers::Books::Create do
   let(:action) { Web::Controllers::Books::Create.new }
@@ -768,7 +765,7 @@ describe Web::Controllers::Books::Create do
 end
 ```
 
-Making these tests pass is easy enough.
+Let's make these tests pass!
 We've already seen how we can write entities to our database, and we can use `redirect_to` to implement our redirection:
 
 ```ruby
@@ -794,11 +791,13 @@ Run options: --seed 63592
 
 # Running:
 
-...............
+...S.S.........
 
 Finished in 0.081961s, 183.0142 runs/s, 305.0236 assertions/s.
 
-12 runs, 14 assertions, 0 failures, 0 errors, 2 skips
+15 runs, 23 assertions, 0 failures, 0 errors, 2 skips
+
+You have skipped tests. Run with --verbose for details.
 ```
 
 Congratulations!
@@ -817,8 +816,7 @@ Let's specify this behaviour as unit tests:
 
 ```ruby
 # spec/web/controllers/books/create_spec.rb
-require 'spec_helper'
-require_relative '../../../../apps/web/controllers/books/create'
+require_relative '../../../spec_helper'
 
 describe Web::Controllers::Books::Create do
   let(:action) { Web::Controllers::Books::Create.new }
@@ -935,9 +933,7 @@ First, we expect a list of errors to be included in the page when `params` conta
 
 ```ruby
 # spec/web/views/books/new_spec.rb
-require 'spec_helper'
-require 'ostruct'
-require_relative '../../../../apps/web/views/books/new'
+require_relative '../../../spec_helper'
 
 describe Web::Views::Books::New do
   let(:params)    { OpenStruct.new(valid?: false, error_messages: ['Title must be filled', 'Author must be filled']) }
@@ -980,7 +976,7 @@ end
 ```
 
 In our template we can loop over `params.errors` (if there are any) and display a friendly message.
-Open up `apps/web/templates/books/new.html.erb`:
+Open up `apps/web/templates/books/new.html.erb` and add the following at the top of the file:
 
 ```erb
 <% unless params.valid? %>
@@ -1003,11 +999,13 @@ Run options: --seed 59940
 
 # Running:
 
-..................
+......S..........
+
+Finished in 0.188950s, 89.9707 runs/s, 179.9413 assertions/s.
 
-Finished in 0.078112s, 230.4372 runs/s, 473.6765 assertions/s.
+17 runs, 34 assertions, 0 failures, 0 errors, 1 skips
 
-15 runs, 27 assertions, 0 failures, 0 errors, 1 skips
+You have skipped tests. Run with --verbose for details.
 ```
 
 ### Improving Our Use Of The Router
@@ -1031,7 +1029,7 @@ resources :books, only: [:index, :new, :create]
 ```
 
 To get a sense of what routes are defined, now we've made this change, you can
-use the special command-line task `routes` to inspect the end result:
+run `bundle exec hanami routes` on your command-line to inspect the end result:
 
 ```
 % bundle exec hanami routes
@@ -1043,10 +1041,10 @@ use the special command-line task `routes` to inspect the end result:
     books POST       /books                         Web::Controllers::Books::Create
 ```
 
-The output for `hanami routes` shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.
+The output shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.
 
 Now we've applied the `resources` helper method, we can take advantage of the named route methods.
-Remember how we built our form using `form_for`?
+Remember how we built our form using `form_for` in `apps/web/templates/books/new.html.erb`?
 
 ```erb
 <%=
@@ -1056,7 +1054,7 @@ Remember how we built our form using `form_for`?
 %>
 ```
 
-It's silly to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
+We don't need to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
 We can use the `routes` helper method that is available in our views and actions to access route-specific helper methods:
 
 ```erb