bullet_train 1.0.35 → 1.0.38

data/docs/super-scaffolding/delegated-types.md

@@ -0,0 +1,328 @@
+# Super Scaffolding with Delegated Types
+
+## Introduction
+In this guide, we’ll cover how to use Super Scaffolding to build views and controllers around models leveraging delegated types. As a prerequisite, you should read the [native Rails documentation for delegated types](https://edgeapi.rubyonrails.org/classes/ActiveRecord/DelegatedType.html). The examples in that documentation only deal with using delegated types at the Active Record level, but they lay a foundation that we won’t be repeating here.
+
+## Terminology
+For the purposes of our discussion here, and building on the Rails example, we’ll call their `Entry` model the **“Abstract Parent”** and the `Message` and `Comment` models the **“Concrete Children”**.
+
+## One of Multiple Approaches
+It’s worth noting there are at least two different approaches you can take for implementing views and controllers around models using delegated types:
+
+1. Centralize views and controllers around the Abstract Parent (e.g. `Account::EntriesController`).
+2. Create separate views and controllers for each Concrete Child (e.g. `Account::MessagesController`, `Account::CommentsController`, etc.)
+
+**In this guide, we’ll be covering the first approach.** This might not seem like an obvious choice for the `Message` and `Comment` examples we’re drawing on from the Rails documentation (it's not), but it is a very natural fit for other common use cases like:
+
+ - “I’d like to add a field to this form and there are many kinds of fields.”
+ - “I’d like to add a section to this page and there are many kinds of sections.”
+
+It’s not to say you can’t do it the other way described above, but this approach has specific benefits:
+
+1. It’s a lot less code. We only have to use Super Scaffolding for the Abstract Parent. It's the only model with views and controllers generated. For the Concrete Children, the only files required are the models, tests, and migrations generated by `rails g model` and some locale Yaml files for each Concrete Child.
+2. Controller permissions can be enforced the same way they always are, by checking the relationship between the Abstract Parent (e.g. `Entry`) and `Team`. All permissions are defined in `app/models/ability.rb` for `Entry` only, instead of each Concrete Child.
+
+## Steps
+
+### 1. Generate Rails Models
+
+Drawing on the [canonical Rails example](https://edgeapi.rubyonrails.org/classes/ActiveRecord/DelegatedType.html), we begin by using Rails' native model generators:
+
+```
+rails g model Entry team:references entryable:references{polymorphic}:index
+rails g model Message subject:string
+rails g model Comment content:text
+```
+
+Note that in this specific approach we don't need a `team:references` on `Message` and `Comment`. That's because in this approach there are no controllers specific to `Message` and `Comment`, so all permissions are being inforced by checking the ownership of `Entry`. (That's not to say it would be wrong to add them for other reasons, we're just keeping it as simple as possible here.)
+
+### 2. Super Scaffolding for `Entry`
+
+```
+bin/super-scaffold crud Entry Team entryable_type:buttons
+```
+
+We use `entryable_type:buttons` because we're going to allow people to choose which type of `Entry` they're creating with a list of buttons. This isn't the only option available to us, but it's the easiest to implement for now.
+
+### 3. Defining Button Options
+
+Super Scaffolding will have generated some initial button options for us already in `config/locales/en/entries.en.yml`. We'll want to update the attribute `name`, field `label` (which is shown on the form) and the available options to reflect the available Concrete Children like so:
+
+```
+fields: &fields
+  entryable_type:
+    name: &entryable_type Entry Type
+    label: What type of entry would you like to create?
+    heading: *entryable_type
+    options:
+      "Message": Message
+      "Comment": Comment
+```
+
+<small>TODO Insert a live example of what `shared/fields/buttons` looks like with these options passed in.</small>
+
+### 4. Add Our First Step to `new.html.erb`
+
+By default, `app/views/account/entries/new.html.erb` has this reference to the shared `_form.html.erb`:
+
+```
+<%= render 'form', entry: @entry %>
+```
+
+However, in this workflow we actually need two steps:
+
+1. Ask the user what type of `Entry` they're creating.
+2. Show the user the `Entry` form with the appropriate fields for the type of entry they're creating.
+
+The first of these two forms is actually not shared between `new.html.erb` and `edit.html.erb`, so we'll copy the contents of `_form.html.erb` into `new.html.erb` as a starting point, like so:
+
+```
+<% if @entry.entryable_type %>
+  <%= render 'form', entry: @entry %>
+<% else %>
+  <%= form_with model: @entry, url: [:new, :account, @team, :entry], method: :get, local: true, class: 'form' do |form| %>
+    <%= render 'account/shared/forms/errors', form: form %>
+    <% with_field_settings form: form do %>
+      <%= render 'shared/fields/buttons', method: :entryable_type, html_options: {autofocus: true} %>
+    <% end %>
+    <div class="buttons">
+      <%= form.submit t('.buttons.next'), class: "button" %>
+      <%= link_to t('global.buttons.cancel'), [:account, @team, :entries], class: "button-secondary" %>
+    </div>
+  <% end %>
+<% end %>
+```
+
+Here's a summary of the updates required when copying `_form.html.erb` into `new.html.erb`:
+
+1. Add the `if @entry.entryable_type` branch logic, maintaining the existing reference to `_form.html.erb`.
+2. Add `@` to the `entry` references throughout. `@entry` is an instance variable in this view, not passed in as a local.
+3. Update the form submission `url` and `method` as seen above.
+4. Remove the Super Scaffolding hooks. Any additional fields that we add to `Entry` would be on the actual `_form.html.erb`, not this step.
+5. Simplify button logic because the form is always for a new object.
+
+### 5. Update Locales
+
+We need to add a locale entry for the "Next Step" button in `config/locales/en/entries.en.yml`. This goes under the `buttons: &buttons` entry that is already present, like so:
+
+```
+buttons: &buttons
+  next: Next Step
+```
+
+Also, sadly, the original locale file wasn't expecting any buttons in `new.html.erb` directly, so we need to include buttons on the `new` page in the same file, below `form: *form`, like so:
+
+```
+new:
+  # ...
+  form: *form
+  buttons: *buttons
+```
+
+### 6. Add Appropriate Validations in `entry.rb`
+
+In `app/models/entry.rb`, we want to replace the default validation of `entryable_type` like so:
+
+```
+ENTRYABLE_TYPES = I18n.t('entries.fields.entryable_type.options').keys.map(&:to_s)
+
+validates :entryable_type, inclusion: {
+  in: ENTRYABLE_TYPES, allow_blank: false, message: I18n.t('errors.messages.empty')
+}
+```
+
+This makes the locale file, where we define the options to present to the user, the single source of truth for what the valid options are.
+
+<small>TODO We should look into whether reflecting on the definition of the delegated types is possible.</small>
+
+Also, to make it easy to check the state of this validation, we'll add `entryable_type_valid?` as well:
+
+```
+def entryable_type_valid?
+  ENTRYABLE_TYPES.include?(entryable_type)
+end
+```
+
+I don't like this method. If you can think of a way to get rid of it or write it better, please let us know!
+
+### 7. Accept Nested Attributes in `entry.rb` and `entries_controller.rb`
+
+In preparation for the second step, we need to configure `Entry` to accept [nested attributes](https://edgeapi.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html). We do this in three parts:
+
+In `app/models/entry.rb`, like so:
+
+```
+accepts_nested_attributes_for :entryable
+```
+
+Also in `app/models/entry.rb`, [Rails will be expecting us](https://stackoverflow.com/questions/45295202/cannot-build-nested-polymorphic-associations-are-you-trying-to-build-a-polymor) to define the following method on the model:
+
+```
+def build_entryable(params = {})
+  raise 'invalid entryable type' unless entryable_type_valid?
+  self.entryable = entryable_type.constantize.new(params)
+end
+```
+
+Finally, in the [strong parameters](https://edgeguides.rubyonrails.org/action_controller_overview.html#strong-parameters) of `app/controllers/account/entries_controller.rb`, _directly below_ this line:
+
+```
+# 🚅 super scaffolding will insert new arrays above this line.
+```
+
+And still within the `permit` parameters, add:
+
+```
+entryable_attributes: [
+  :id,
+
+  # Message attributes:
+  :subject,
+
+  # Comment attributes:
+  :content,
+],
+```
+
+<small>(Eagle-eyed developers will note an edge case here where you would need to take additional steps if you had two Concrete Children classes that shared the same attribute name and you only wanted submitting form data for that attribute to be permissible for one of the classes. That situation should be exceedingly rare, and you can always write a little additional code here to deal with it.)</small>
+
+### 8. Populate `@entry.entryable` in `entries_controller.rb`
+
+Before we can present the second step to users, we need to react to the user's input from the first step and initialize either a `Message` or `Comment` object and associate `@entry` with it. We do this in the `new` action of `app/controllers/account/entries_controller.rb` and we can also use the `build_entryable` method we created earlier for this purpose, like so:
+
+```
+def new
+  if @entry.entryable_type_valid?
+    @entry.build_entryable
+  elsif params[:commit]
+    @entry.valid?
+  end
+end
+```
+
+### 9. Add the Concrete Children Fields to the Second Step in `_form.html.erb`
+
+Since we're now prompting for the entry type on the first step, we can remove the following from the second step in `app/views/account/entries/_form.html.erb`:
+
+```
+<%= render 'shared/fields/buttons', method: :entryable_type, html_options: {autofocus: true} %>
+```
+
+But we need to keep track of which entry type they selected, so we replace it with:
+
+```
+<%= form.hidden_field :entryable_type %>
+```
+
+Also, below that (and below the Super Scaffolding hook), we want to add the `Message` and `Comment` fields as [nested forms](https://guides.rubyonrails.org/form_helpers.html#nested-forms) like so:
+
+```
+<%= form.fields_for :entryable, entry.entryable do |entryable_form| %>
+  <%= entryable_form.hidden_field :id %>
+  <% with_field_settings form: entryable_form do %>
+    <% case entryable_form.object %>
+    <% when Message %>
+      <%= render 'shared/fields/text_field', method: :subject %>
+    <% when Comment %>
+      <%= render 'shared/fields/trix_editor', method: :content %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+We add this _below_ the Super Scaffolding hook because we want any additional fields being added to `Entry` directly to appear in the form _above_ the nested form fields.
+
+### 10. Add Attributes of the Concrete Children to `show.html.erb`
+
+Under the Super Scaffolding hook in `app/views/account/entries/show.html.erb`, add the following:
+
+```
+<% with_attribute_settings object: @entry.entryable, strategy: :label do %>
+  <% case @entry.entryable %>
+  <% when Message %>
+    <%= render 'shared/attributes/text', attribute: :subject %>
+  <% when Comment %>
+    <%= render 'shared/attributes/html', attribute: :content %>
+  <% end %>
+<% end %>
+```
+
+This will ensure the various different attributes of the Concrete Children are properly presented. However, the `label` strategy for these attribute partials depend on the locales for the individual Concrete Children being defined, so we need to create those files now, as well:
+
+`config/locales/en/messages.en.yml`:
+```
+en:
+  messages: &messages
+    fields:
+      subject:
+        _: &subject Subject
+        label: *subject
+        heading: *subject
+  account:
+    messages: *messages
+  activerecord:
+    attributes:
+      message:
+        subject: *subject
+```
+
+`config/locales/en/comments.en.yml`:
+```
+en:
+  comments: &comments
+    fields:
+      content:
+        _: &content Content
+        label: *content
+        heading: *content
+  account:
+    comments: *comments
+  activerecord:
+    attributes:
+      comment:
+        content: *content
+```
+
+### 11. Actually Use Delegated Types?
+
+So everything should now be working as expected, and here's the crazy thing: **We haven't even used the delegated types feature yet.** That was part of the beauty of delegated types when it was released in Rails 6.1: It was really just a formalization of an approach that folks had already been doing in Rails for years.
+
+<center>
+<br>
+<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Really loving the PR for Rails 6.1&#39;s Delegated Types. From the application developer level, very little of it feels &quot;new&quot;. Instead, the experience reads very similar to what many of us were already doing with the existing tools, but even smoother! <a href="https://t.co/6UkxXNCvaa">https://t.co/6UkxXNCvaa</a></p>&mdash; Andrew Culver (@andrewculver) <a href="https://twitter.com/andrewculver/status/1338189146213543951?ref_src=twsrc%5Etfw">December 13, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+<br>
+</center>
+
+To now incorporate delegated types as put forward in the original documentation, we want to remove this line in `app/models/entry.rb`:
+
+```
+belongs_to :entryable, polymorphic: true
+```
+
+And replace it with:
+
+```
+delegated_type :entryable, types: %w[ Message Comment ]
+```
+
+We also want to follow the other steps seen there, such as defining an `Entryable` concern in `app/models/concerns/entryable.rb`, like so:
+
+```
+module Entryable
+  extend ActiveSupport::Concern
+
+  included do
+    has_one :entry, as: :entryable, touch: true
+  end
+end
+```
+
+And including the `Entryable` concern in both `app/models/message.rb` and `app/models/comment.rb` like so:
+
+```
+include Entryable
+```
+
+## Conclusion
+
+That's it! You're done! As mentioned at the beginning, this is only one of the ways to approach building views and controllers around your models with delegated types, but it's a common one, and for the situations where it is the right fit, it requires a lot less code and is a lot more [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) than scaffolding views and controllers around each individual delegated type class.

data/docs/super-scaffolding.md

@@ -0,0 +1,246 @@
+# Code Generation with Super Scaffolding
+
+Super Scaffolding is Bullet Train’s code generation engine. Its goal is to allow you to produce production-ready CRUD interfaces for your models while barely lifting a finger, and it handles a lot of other grunt-work as well.
+
+Here’s a list of what Super Scaffolding takes care of for you each time you add a model to your application:
+
+ - It generates a basic CRUD controller and accompanying views.
+ - It generates a Yaml locale file for the views’ translatable strings.
+ - It generates type-specific form fields for each attribute of the model.
+ - It generates an API controller and an accompanying entry in the application’s API docs.
+ - It generates a serializer that’s used by the API and when dispatching webhooks.
+ - It adds the appropriate permissions for multitenancy in CanCanCan’s configuration file.
+ - It adds the model’s table view to the show view of its parent.
+ - It adds the model to the application’s navigation (if applicable).
+ - It generates breadcrumbs for use in the application’s layout.
+ - It generates the appropriate routes for the CRUD controllers and API endpoints.
+
+When adding just one model, Super Scaffolding generates ~30 different files on your behalf.
+
+## Living Templates
+
+Bullet Train's Super Scaffolding engine is a unique approach to code generation, based on template files that are functional code instead of obscure DSLs that are difficult to customize and maintain. Super Scaffolding automates the most repetitive and mundane aspects of building out your application's basic structure. Furthermore, it does this without leaning on the magic of libraries that force too high a level of abstraction. Instead, it generates standard Rails code that is both ready for prime time, but is also easy to customize and modify.
+
+## Prerequisites
+
+Before getting started with Super Scaffolding, we recommend reading about [the philosophy of domain modeling in Bullet Train](/docs/topics/domain-modeling.md).
+
+## Usage
+
+The Super Scaffolding shell script provides its own documentation. If you're curious about specific scaffolders or parameters, you can run the following in your shell:
+
+```
+bin/super-scaffold
+```
+
+## Examples
+
+### 1. Basic CRUD Scaffolding with `crud`
+
+Let's implement the following feature:
+
+> An organization has many projects.
+
+First, generate the model with the standard Rails generator:
+
+```
+rails g model Project team:references name:string
+```
+
+In the above example, `team` represents the model that a `Project` primarily belongs to.
+
+⚠️ Don't run migrations right away. It would be fine in this case, but sometimes the subsequent Super Scaffolding step actually updates the migration as part of its magic.
+
+Next, run the `crud` scaffolder:
+
+```
+bin/super-scaffold crud Project Team name:text_field
+rake db:migrate
+```
+
+In the above example, `text_field` was selected from [the list of available field partials](/docs/field-partials.md). We'll show examples with `trix_editor` and `super_select` later.
+
+### 2. Nested CRUD Scaffolding with `crud`
+
+Building on that example, let's implement the following feature:
+
+```
+A project has many goals.
+```
+
+Again, we'll generate the model using the standard Rails generator:
+
+```
+rails g model Goal project:references description:string
+```
+
+You can see in the example above that there is no direct reference to team, but to `project` instead, since that's where a `Goal` belongs.
+
+Now, run the `crud` scaffolder:
+
+```
+bin/super-scaffold crud Goal Project,Team description:text_field
+rake db:migrate
+```
+
+You can see in the example above how we've specified `Project,Team`, because we want to specify the entire chain of ownership back to the `Team`. This allows Super Scaffolding to automatically generate the required permissions.
+
+### 3. Adding New Fields with `crud-field`
+
+One of Bullet Train's most valuable features is the ability to add new fields to existing scaffolded models. When you add new fields with the `crud-field` scaffolder, you don't have to remember to add that same attribute to table views, show views, translation files, API endpoints, serializers, tests, documentation, etc.
+
+Building on the earlier example, consider the following new requirement:
+
+> In addition to a name, a project can have a description.
+
+First, use the standard Rails migration generator to add the attribute in the database:
+
+```
+rails g migration add_description_to_projects description:text
+```
+
+Then, use the `crud-field` scaffolder to add it throughout the application:
+
+```
+bin/super-scaffold crud-field Project description:trix_editor
+rake db:migrate
+```
+
+As you can see, when we're using `crud-field`, we don't need to supply the chain of ownership back to `Team`.
+
+### 4. Adding Option Fields with Fixed, Translatable Options
+
+Continuing with the earlier example, let's address the following new requirement:
+
+> Users can specify the current project status.
+
+We have multiple [field partials](/docs/field-partials.md) that we could use for this purpose, including `buttons`, `options`, or `super_select`.
+
+In this example, let's add a status attribute and present it as buttons:
+
+```
+rails g migration add_status_to_projects status:string
+bin/super-scaffold crud-field Project status:buttons
+```
+
+By default, Super Scaffolding configures the buttons as "One", "Two", and "Three", but in this example you can edit those options in the `fields` section of `config/locales/en/projects.en.yml`. For example, you could specify the following options:
+
+```
+planned: Planned
+started: Started
+completed: Completed
+```
+
+If you want new `Project` models to be set to `planned` by default, you can add that to the migration file that was generated before running it, like so:
+
+```
+add_column :projects, :status, :string, default: "planned"
+```
+
+### 5. Scaffolding `belongs_to` Associations, Team Member Assignments
+
+Continuing with the example, consider the following requirement:
+
+> A project has one specific project lead.
+
+Although you might think this calls for a reference to `User`, we've learned the hard way that it's typically much better to assign resources on a `Team` to a `Membership` on the team instead. For one, this allows you to assign resources to new team members that haven't accepted their invitation yet (and don't necessarily have a `User` record yet.)
+
+We can accomplish this like so:
+
+```
+rails g migration add_lead_to_projects lead:references
+```
+
+Then, to add the field, we specify the following:
+
+```
+bin/super-scaffold crud-field Project lead_id:super_select[class_name=Membership]
+rake db:migrate
+```
+
+There are two important things to point out here:
+
+1. When we use `rails g model` or `rails g migration`, we specify the `references` column name as `lead`, but when we're specifying the _field_ we want to scaffold, we specify it as `lead_id`, because that's the name of the attribute on the form, in strong parameters, etc.
+2. We have to specify the model name with the `class_name` option so that Super Scaffolding can fully work it's magic. We can't reflect on the association, because at this point the association isn't properly defined yet. With this information, Super Scaffolding can handle that step for you.
+
+Finally, Super Scaffolding will prompt you to edit `app/models/project.rb` and implement the required logic in the `valid_leads` method. This is a template method that will be used to both populate the select field on the `Project` form, but also enforce some important security concerns in this multi-tenant system. In this case, you can define it as:
+
+```
+def valid_leads
+  team.memberships.current_and_invited
+end
+```
+
+(The `current_and_invited` scope just filters out people that have already been removed from the team.)
+
+### 6. Scaffolding Has-Many-Through Associations with `join-model`
+
+Finally, working from the same example, imagine the following requirement:
+
+> A project can be labeled with one or more project-specific tags.
+
+We can accomplish this with a new model, a new join model, and a `super_select` field.
+
+First, let's create the tag model:
+
+```
+rails g model Projects::Tag team:references name:string
+bin/super-scaffold crud Projects::Tag Team name:text_field
+```
+
+Note that project tags are specifically defined at the `Team` level. The same tag can be applied to multiple `Project` models.
+
+Now, let's create a join model for the has-many-through association:
+
+```
+rails g model Projects::AppliedTag project:references tag:references
+```
+
+We're not going to scaffold this model with the typical `crud` scaffolder, but some preparation is needed before we can use it with the `crud-field` scaffolder, so we need to do the following:
+
+```
+bin/super-scaffold join-model Projects::AppliedTag project_id[class_name=Project] tag_id[class_name=Projects::Tag]
+```
+
+All we're doing here is specifying the name of the join model, and the two attributes and class names of the models it joins. Note again that we specify the `_id` suffix on both of the attributes.
+
+Now that the join model has been prepared, we can use the `crud-field` scaffolder to create the multi-select field:
+
+```
+bin/super-scaffold crud-field Project tag_ids:super_select[class_name=Projects::Tag]
+rake db:migrate
+```
+
+Just note that the suffix of the field is `_ids` plural, and this is an attribute provided by Rails to interact with the `has_many :tags, through: :applied_tags` association.
+
+The `crud-field` step will ask you to define the logic for the `valid_tags` method in `app/models/project.rb`. You can define it like so:
+
+```
+def valid_tags
+  team.projects_tags
+end
+```
+
+Honestly, it's crazy that we got to the point where we can handle this particular use case automatically. It seems simple, but there is so much going on to make this feature work.
+
+## Additional Notes
+
+### `TangibleThing` and `CreativeConcept`
+
+In order to properly facilitate this type of code generation, Bullet Train includes two models in the `Scaffolding` namespace:
+
+1. `Scaffolding::AbsolutelyAbstract::CreativeConcept`
+2. `Scaffolding::CompletelyConcrete::TangibleThing`
+
+Their peculiar naming is what's required to ensure that their corresponding view and controller templates can serve as the basis for any combination of different model naming or [namespacing](https://blog.bullettrain.co/rails-model-namespacing/) that you may need to employ in your own application.
+
+### Hiding Scaffolding Templates
+
+You won't want your end users seeing the Super Scaffolding templates in your environment, so you can disable their presentation by setting `HIDE_THINGS` in your environment. For example, you can add the following to `config/application.yml`:
+
+```
+HIDE_THINGS: true
+```
+
+## Advanced Examples
+ - [Super Scaffolding with Delegated Types](/docs/super-scaffolding/delegated-types.md)

data/docs/teams.md

@@ -0,0 +1,8 @@
+# Teams
+
+Please read the article providing [an overview of organizational teams in Bullet Train](https://blog.bullettrain.co/teams-should-be-an-mvp-feature/). This article doesn't just explain how `Team`, `Membership`, `Invitation` and `Role` relate and function in Bullet Train, but it also explains how to properly think about resource ownership even in complex scenarios. Furthermore, it touches on ways in which Bullet Train's organizational structure has been successfully extended in more complicated systems.
+
+Rather than simply duplicating the content of that blog article here, we'll focus on keeping that article up-to-date so it can benefit not only incoming Bullet Train developers, but also the broader developer ecosystem.
+
+## Related Topics
+ - [Permissions](/docs/permissions.md)

data/docs/testing.md

@@ -0,0 +1,34 @@
+# Automated Test Suite
+All of Bullet Train’s core functionality is verifiable using the provided test suite. This foundation of headless browser integration tests took a ton of time to write, but they can give you the confidence and peace of mind that you haven't broken any key functionality in your application before a deploy.
+
+You can run the test suite with the following command in your shell:
+
+```
+rails test:system
+```
+
+## Fixing Broken Tests
+
+### 1. Run Chrome in Non-Headless Mode
+
+When debugging tests, it's important to be able to see what Capybara is seeing. You can disable the headless browser mode by prefixing `rails test` like so:
+
+```
+MAGIC_TEST=1 rails test
+```
+
+When you run the test suite with `MAGIC_TEST` set in your environment like this, the browser will appear on your screen after the first Capybara test starts. (This may not be the first test that runs.) Be careful not to interact with the window when it appears, as sometimes your interactions can cause the test to fail needlessly.
+
+### 2. Insert `binding.pry`.
+
+Open the failing test file and insert `binding.pry` right before the action or assertion that is causing the test to fail. After doing that, when you run the test, it will actually stop and open a debugging console while the browser is still open to the appropriate page where the test is beginning to fail. You can use this console and the open browser to try and figure out why the test is failing. When you're done, hit <kbd>Control</kbd> + <kbd>D</kbd> to exit the debugger and continue letting the test run.
+
+## Super Scaffolding Test Suite
+In addition to the standard application test suite, there is a separate test available that doesn't run by default that you can run in CI to ensure you haven't accidentally broken the full function of Super Scaffolding in your application. Before the test runs, there is a setup script that runs a number of Super Scaffolding commands, so you should never run the test in anything but a clean working copy that can be reset when you're done.
+
+You can run the setup script and test like so:
+
+```
+test/bin/setup-super-scaffolding-system-test
+rails test test/system/super_scaffolding_test.rb
+```