Active Rails

To start building the application you’ll be developing throughout this book, run the good-old rails command, preferably outside the directory of the previous application. Call this app ticketee, the Australian slang for a person who validates tickets on trains in an attempt to catch fare evaders. It also has to do with this project being a ticket-tracking application, and a Rails application, at that.^[1] To generate this application, run this command:

Presto, it’s done! From this bare-bones application, you’ll build an application that does the following:

You can’t do all this with a command as simple as rails new [application_name], but you can do it step by step and test it along the way so you develop a stable and worthwhile application.

Throughout the development of the application, we advise you to use a version-control system. The next section covers that topic using Git. You’re welcome to use a different version-control system, but this book uses Git exclusively.

The development environment is used for your local application, such as when you’re playing with it in the browser on your local machine. In development mode, page and class caching are turned off, so requests may take a little longer than they do in production mode. (Don’t worry—this is only the case for larger applications.) Things like more detailed error messages are also turned on, for easier debugging.

The test environment is used when you run the automated test suite for the application. This environment is kept separate from the development environment so your tests start with a clean database to ensure predictability, and so you can include extra gems specifically to aid in testing.

The production environment is used when you finally deploy your application out into the world for others to use. This mode is designed for speed, and any changes you make to your application’s classes aren’t effective until the server is restarted.

This automatic requiring of gems in the Rails environment groups is done by this line in config/application.rb:

The Rails.groups line provides two groups for Bundler to require: default and development. The latter will change depending on the environment that you’re running. This code will tell Bundler to load only the gems in the "default" group (which is all gems not in any specific group), as well as any gems in a group that has the same name as the environment.

Chapter 2 focused on Behavior Driven Development (BDD), and, as was more than hinted at, you’ll be using it to develop this application. To get started, alter the Gemfile to ensure that you have the correct gem for RSpec for your application. To add the rspec-rails gem, we’ll add this line to the :development, :test group in our Gemfile:

This group in our Gemfile lists all the gems that will be loaded in the development and test environments of our application. These gems will not be available in a production environment. We’re adding rspec-rails to this group because we’re going to need a generator from it to be available in development. Additionally, when you run a generator for a controller or model, it’ll use RSpec, rather than the default Test::Unit, to generate the tests for that class.

You’ve specified a version number with ~> 4.0.0 ^[4] which tells RubyGems you want rspec-rails version 4.0.0 or higher, but less than rspec-rails 4.1.0. This means when RSpec releases 4.0.1 and you go to install your gems, RubyGems will install the latest version it can find, rather than only 4.0.1.

The other gem that we’ll be using here is the capybara gem, but that is already in our Gemfile:

As we saw in the last chapter, Capybara can simulate actions on our application, allowing us to test the application automatically.

Capybara also supports real browser testing. If you tell RSpec that your test is a JavaScript test, it will open a new Firefox window and run the test there - you’ll actually be able to see your tests as they occur, and your application will behave exactly the same as it does when you view it yourself. You’ll use this extensively when we start writing JavaScript in chapter 9.

To install these gems to your system, run this command:

With the necessary gems for the application installed, you should next run the rspec:install generator, a generator provided by RSpec to set your Rails application up for testing.

You can also remove the default generated test directory in the root folder of your application - you won’t be using it. You’ll write tests under the spec directory instead.

With this generated code in place, you should make a commit so you have another base to roll back to if anything goes wrong:

To define the index action in your controller, you must define a method in the ProjectsController class, just as you did when you generated your first application, as shown in the following listing.

If you run bundle exec rspec again, this time Rails complain of a missing template projects/index:

This error says that we’re missing a template for the request format of text/html. This means that we will need to create a view.

To generate this view, create the app/views/projects/index.html.erb file and leave it blank for now. This file is called index.html.erb so that we have the correct format (HTML), and this file will be using ERB to evaluate some Ruby to generate some of that HTML, hence the .erb extension.

Let’s run this test one more time:

You’ve defined a home page for your application by defining a root route, generating a controller, putting an action in it, and creating a view for that action. Now Capybara is successfully navigating to it, and rendering it. That’s the first step in the first test passing for your first application, and it’s a great first step!

The second line in your spec is now failing, and it’s up to you to fix it. You need a link on the root page of your application that reads "New Project". That link should go in the view of the controller that’s serving the root route request: app/views/projects/index.html.erb. Create a new file at app/views/projects/index.html.erb and open it for editing. Put the "New Project" link in by using the link_to method:

This single line reintroduces two old concepts and a new one: ERB output tags, the link_to method (both of which you saw in chapter 1), and the mysterious new_project_path method.

As a refresher, in ERB, when you use <%= (known as an ERB output tag), you’re telling ERB that whatever the output of this Ruby is, put it on the page. If you only want to evaluate Ruby, you use an ERB evaluation tag <%, which doesn’t output content to the page but only evaluates it. Both of these tags end in %>.

The link_to method in Rails generates an <a> tag with the text of the first argument and the href of the second argument. This method can also be used in block format if you have a lot of text you want to link to:

Where new_project_path comes from deserves its own section. It’s the very next one.

A model is used to perform queries on a database, to fetch or store information. Because models by default inherit from Active Record, you don’t have to set up anything extra. Run the following command to generate your first model:

This syntax is similar to the controller generator’s syntax except that you specified you want a model, not a controller. When the generator runs, it generates not only the model file but also a migration containing the code to create the table for the model, containing the specified fields. You can specify as many fields as you like after the model’s name. They default to string type, so you didn’t need to specify them. If you wanted to be explicit, you could use a colon followed by the field type, like this:

A model provides a place for any business logic that your application does. One common bit of logic is the way your application interacts with a database. A model is also the place where you define validations (seen later in this chapter), associations (discussed in chapter 5) and scopes (easy-to-use filters for database calls, discussed in chapter 7), among other things. To perform any interaction with data in your database, you go through a model.^[7]

Migrations are effectively version control for the database. They’re defined as Ruby classes, which allows them to apply to multiple database schemas without having to be altered. All migrations have a change method in them when they’re first defined. For example, the code shown in the following listing comes from the migration that was just generated.

When you run the migration forward (using bundle exec rails db:migrate), it creates the table in the database. When you roll the migration back (with rails db:rollback), it deletes (or drops) the table from the database. If you need to do something different on the up and down parts, you can use those methods instead:

Here, the up method would be called if you ran the migration forward, and the down method would be run if you ran it backward.

This syntax is especially helpful if the migration does something that has a reverse function that isn’t clear, such as removing a column^[8]:

This is because Active Record won’t know what type of field to re-add this column as, so you must tell it what to do in the case of this migration being rolled back.

In our projects migration, the first line of the change method tells Active Record that you want to create a table called projects. You call this method using the block format, which returns an object that defines the table. To add fields to this table, you call methods on the block’s object (called t in this example and in all model migrations), the name of which usually reflects the type of column it is; the first argument is the name of that field. The timestamps method is special: it creates two fields, created_at and updated_at, which are by default set to the current time in co-ordinated universal time (UTC)^[9] by Rails when a record is created and updated, respectively.

A migration doesn’t automatically run when you create it—you must run it yourself using this command:

These commands migrate the database up to the latest migration, which for now is the only migration. If you create a whole slew of migrations at once, then invoking rails db:migrate will migrate them in the order in which they were created. This is the purpose of the timestamp in the migration filename - to keep the migrations in chronological order.

With this model created and its related migration run, your test doesn’t get any further but you can start building out the form to create a new project.

To add this field to the new action’s view, you can put it in a form, but not just any form: a form_with, as in the following listing.

So many new things!

Starting at the top, the form_with method is Rails' way of building forms for Active Record objects. You pass it the @project object you defined in your controller as the argument for the model option and with this, the helper does much more than simply place a form tag on the page. form_with inspects the @project object and creates a form builder specifically for that object. The two main things it inspects are whether it’s a new record and what the class name is.

Determining what action attribute the form has (the URL the form submits its data to) depends on whether the object is a new record or not. A record is classified as new when it hasn’t been saved to the database. This check is performed internally by Rails using the persisted? method, which returns true if the record is stored in the database or false if it’s not.

The class of the object also plays a pivotal role in where the form is sent - Rails inspects this class and, from it, determines what the route should be. Because @project is new and is an object of class Project, Rails determines that the submit URL will be the result of projects_path, which will mean the route is /projects and the method for the form is POST. Therefore, a request is sent to the create action in ProjectsController.

If we were to look at the form’s generated HTML, we would see this:

The action and method in combination will make this form submit to POST /projects, sending the form’s data to the create action within ProjectsController.

After that part of form_with is complete, you use the block syntax to receive a form variable, which is a FormBuilder object. You can use this object to define your form’s fields. The first element you define is a label. label tags directly relate to the input fields on the page and serve two purposes. First, they give users a larger area to click, rather than just the field, radio button, or check box. The second purpose is so you can reference the label’s text in the test, and Capybara will know what field to fill in.

After the label, you put the text_field, which renders an <input> tag corresponding to the label and the field. The output tag looks like this:

Then you use the submit method to provide users with a submit button for your form. Because you call this method on the form object, Rails checks whether the record is new and sets the text to read "Create Project" if the record is new or "Update Project" if it isn’t. You’ll see this in use a little later when you build the edit action. For now, focus on the new action!

Now, running bundle exec rspec once more, you can see that your spec is one step closer to finishing—the field fill-in steps have passed:

Capybara finds the label containing the "Name" text you ask for in your scenario, and fills out the corresponding field with the value we specify. Capybara has a number of ways to locate a field, such as by the name of the corresponding label, the id attribute of the field, or the name attribute. The last two look like this:

Capybara does the same thing for the "Description" field, and then will click the button we told it to click. The spec is now complaining about a missing action called create. Let’s fix that.

To define this action, you define the create method underneath the new method in the ProjectsController, as in the following listing.

The Project.new method takes one argument, which is a list of attributes that will be assigned to this new Project object. For now, we’re just calling that list project_params.

After you build your new @project instance, you call @project.save to save it to the projects table in your database. Before that happens, though, Rails will run all the data validations on the model, ensuring that it’s valid. At the moment, you have no validations on the model, so it will save just fine.

The flash method in your create action is a way of passing messages to the next request, and it takes the form of a hash. These messages are stored in the session and are cleared at the completion of the next request. Here you set the :notice key of the flash hash to be "Project has been created" to inform the user what has happened. This message is displayed later, as is required by the final step in your feature.

The redirect_to method can take several different arguments - an object, or the name of a route. If an object is given, Rails inspects it to determine what route it should go to: in this case, project_path(@project) because the object has now been saved to the database. This method generates the path of something such as /projects/:id, where :id is the record’s id attribute assigned by your database system. The redirect_to method tells the browser to begin making a new request to that path and sends back an empty response body; the HTTP status code will be a "302 Redirect", and point to the currently non-existent show action.

If you run bundle exec rspec now, you’ll get an error about an undefined local variable or method "project_params".

Where does the data we want to make a new project from, come from? They come from the params provided to the controller, available to all Rails controller actions.

The params method returns the parameters passed to the action, such as those from the form or query parameters from a URL, as a HashWithIndifferentAccess object. These are different from normal Hash objects, because you can reference a String key by using a matching Symbol and vice versa. In this case, the params hash looks like this:

You can easily see what params your controller is receiving by looking at the server logs in your terminal console. If you run your rails server, visit http://localhost:3000/projects/new and submit the data that your test is trying to submit, you’ll see the following in the terminal:

And the parameters are listed right there.

All the hashes nested inside the params hash are also HashWithIndifferentAccess hashes. If you want to get the name key from the project hash here, you can use either { :name ⇒ "Visual Studio Code" }[:name], as in a normal Hash object, or { :name ⇒ "Visual Studio Code" }['name']; you may use either the String or the Symbol version—it doesn’t matter.

The first key in the params hash, commit, comes from the submit button of the form, which has the value "Create Project". This is accessible as params[:commit]. The second key, action, is one of two parameters always available; the other is controller. These represent exactly what their names imply: the controller and action of the request, accessible as params[:controller] and params[:action], respectively. The final key, project, is, as mentioned before, a HashWithIndifferentAccess. It contains the fields from your form and is accessible via params[:project]. To access the name key in the params[:project] object, use params[:project][:name], which calls the [] method on params to get the value of the :project key and then, on the resulting hash, calls [] again, this time with the :name key to get the name of the project passed in.

params[:project] has all the data we need to pass to Project.new, but we can’t just pass it directly in. If you try to substitute project_params with params[:project] in your controller, and then run rspec again, you’ll get the following error:

Oooh, forbidden attributes. Sounds scary. This is important: it’s one form of security help that Rails gives you via a feature called strong parameters. You don’t want to accept just any submitted parameters: you want to accept the ones that you want and expect, and no more. That way, someone can’t mess around with your application by doing things like tampering with the form and adding new fields, before submitting it.

Change the ProjectsController code to add a new definition for the project_params method.

You now call the require method on your params, and you require that the :project key exists. You also allow it to have :name and :description entries - any other fields submitted will be discarded. Finally, you wrap up that logic into a method so you can use it in other actions, and you make it private so you don’t expose it as some kind of weird action! We’ll use this method in one other action in this controller later on, the update action.

With that done, run bundle exec rspec again, and you’ll get a new error:

The test has made it through the create action, followed the redirect we issued, and now it’s stuck on the next request - the page we redirected to, the show action.

The show action is responsible for displaying a single record’s information. Retrieving a record to display is done by default using the record’s ID. You know the URL for this page will be something like /projects/1, but how do you get the 1 from that URL? Well, when you use resource routing, as you have done already, the 1 part of this URL is available as params[:id], just as params[:controller] and params[:action] are also automatically made available by Rails. You can then use this params[:id] parameter in your show action to find a specific Project object. In this case, the show action should be showing the newly created project.

Put the code from the following listing into app/controllers/projects_controller.rb to set up the show action. Make sure it comes above the private declaration, or you won’t be able to use it as an action!

You pass the params[:id] object to Project.find. This gives you a single Project object that relates to a record in the database, which has its id field set to whatever params[:id] is. If Active Record can’t find a record matching that ID, it raises an ActiveRecord::RecordNotFound exception.

When you rerun bundle exec rspec spec/features/creating_projects_spec.rb, you’ll get an error telling you that the show action’s template is missing:

You can create the file app/views/projects/show.html.erb with the following content for now to display the project’s name and description:

It’s a pretty plain page for a project, but it will serve our purpose. When you run the test again with bundle exec rspec spec/features/creating_projects_spec.rb, you see this message:

This error message shows that the "Project has been created." text isn’t being displayed on the page. Therefore, you must put it somewhere, but where?

The best location is in the application layout, located at app/views/layouts/application.html.erb. This file provides the layout for all templates in your application, so it’s a great spot to output a flash message - no matter what controller we set it in, it will be rendered on the page.

The application layout is quite the interesting file:

The first line sets up the doctype to be HTML for the layout, and three new methods are used: stylesheet_link_tag, javascript_importmap_tags, and csrf_meta_tags.

The stylesheet_link_tag and javascript_importmap_tags methods include CSS and JavaScript assets for our application.

The csrf_meta_tags is for protecting your forms from cross-site request forgery (CSRF^[10]) attacks. These types of attacks were mentioned a short while ago when we looked at the parameters for the create action; when we were talking about the authenticity_token parameter. The csrf_meta_tags helper creates two meta tags, one called csrf-param and the other csrf-token. This unique token works by setting a specific key on forms that is then sent back to the server. The server checks this key, and if the key is valid, the form is deemed valid. If the key is invalid, an ActionController::InvalidAuthenticityToken exception occurs and the user’s session is reset as a precaution.

Later in app/views/layouts/application.html.erb is the single line:

This line indicates to the layout where the current action’s template is to be rendered. Create a new line just before <%= yield %>, and place the following code there:

This code renders all the flash messages that are defined, regardless of their name and the controller they come from. These lines will display the flash[:notice] that you set up in the create action of the ProjectsController. Run bundle exec rspec again, and see that the test is now fully passing:

Why do you have three pending tests? If you examine the output more closely, you’ll see this:

The key part is that "or delete". Let’s delete those two files, because you’re not using them yet:

Afterward, run bundle exec rspec one more time:

Yippee! You have just written your first BDD test for this application! That’s all there is to it. If this process feels slow, that’s how it’s supposed to feel when you’re new to anything. Remember when you were learning to drive a car? You didn’t drive like Michael Schumacher as soon as you got behind the wheel. You learned by doing it slowly and methodically. As you progressed, you were able to do it more quickly, as you can all things with practice.

To get this test to do what you want it to do, you’ll need to add a validation. Validations are defined on the model and are run before the data is saved to the database. To define a validation to ensure that the name attribute is provided when a project is created, open the app/models/project.rb file and make it look like the following listing.

The validates method’s usage is exactly how you used it for the first time in chapter 1. It tells the model that you want to validate the name field, and that you want to validate its presence. There are other kinds of validations as well; for example, the :uniqueness key, when passed true as the value, validates the uniqueness of this field as well, ensuring that only one record in the table has that specific value.^[12]

With the presence validation in place, you can experiment with the validation by using the Rails console, which allows you to have all the classes and the environment from your application loaded in a sandbox environment. You can launch the console with this command:

or with its shorter alternative:

If you’re familiar with Ruby, you may realize that this is effectively IRB with some Rails sugar on top. For those of you new to both, IRB stands for Interactive Ruby, and it provides an environment for you to experiment with Ruby without having to create new files. The console prompt looks like this:

At this prompt^[13], you can enter any valid Ruby, and it’ll be evaluated. But for now, the purpose of opening this console was to test the newly appointed validation. To do this, try to create a new project record by calling the create method. The create method is similar to the new method, but it attempts to create an object and then a database record for it rather than just the object. You use it identically to the new method:

Here you get a new Project object with the name and description attributes set to nil, as you should expect because you didn’t specify it. The id attribute is nil too, which indicates that this object isn’t persisted (saved) in the database.

If you comment out or remove the validation from in the Project class and type reload! in your console, the changes you just made to the model are reloaded. When the validation is removed, you have a slightly different outcome when you call Project.create:

Here, the name field is still expectedly nil, but the other three attributes have values. Why? When you call create on the Project model, Rails builds a new Project object with any attributes you pass it^[14] and checks to see if that object is valid. If it is, Rails sets the created_at and updated_at attributes to the current time and then saves the object to the database. After it’s saved, the id is returned from the database and set on your object. This object is valid, according to Rails, because you removed the validation, and therefore Rails goes through the entire process of saving.

The create method has a bigger, meaner brother called create! (pronounced create BANG!). Re-add or uncomment the validation from the model, and type reload! in the console, and you’ll see what this mean variant does with this line:

The create! method, instead of nonchalantly handing back a Project object regardless of any validations, raises an ActiveRecord::RecordInvalid exception if any of the validations fail; it shows the exception followed by a large stacktrace, which you can safely ignore for now. You’re notified which validation failed. To stop it from failing, you must pass in a name attribute, and create will happily return a saved Project object:

That’s how to use create to test your validations in the console. We’ve created some bad data in our database during our experimentation, we should clean that up before we continue.

Back in your ProjectsController, we’re using the method shown in the following listing instead.

If the validations pass, save here will return true. You can use this to your advantage to show the user an error message when this returns false by using it in an if statement. Make the create action in the ProjectsController look like the following listing.

Now, if the @project object has a name attribute — meaning it’s valid — save returns true and executes everything between if and else. If it isn’t valid, then everything between else and the following end is executed. In the else, you specify a different key for the flash message because you’ll want to style alert messages differently from notices later in the application’s lifecycle. When good things happen, the messages for them will be colored with a green background. When bad things happen, red.

When you run bundle exec rspec spec/features/creating_projects_spec.rb here, the line in the spec that checks for the "Project has not been created." message now doesn’t fail; so, it goes to the next line, which checks for the "Name can’t be blank" message. You haven’t done anything to make this message appear on the page right now, which is why the test is failing again:

The validation errors for the project aren’t being displayed on this page, which is causing the test to fail. To display validation errors in the view, you need to code something up yourself.

When an object fails validation, Rails will populate the errors of the object with any validation errors. You can test this back in your Rails console:

ActiveModel::Errors provides some nice helper methods for working with the validation errors, that we can use in our views to display the errors back to the user. Directly under this form_with line, on a new line, insert the following into app/views/projects/new.html.erb to display the error messages in the form.

Error messages for the object represented by your form, the @project object, will now be displayed by each. When you run bundle exec rspec, you get this output:

Commit and push, and then you’re done with this story!