brut 0.17.0 → 0.18.0

data/brutrb.com/end-to-end-tests.md

@@ -1,176 +0,0 @@
-# End to End Tests
-
-Is there a greater pain the world than an end-to-end test? Is there a more punishing API than trying to
-convince a browser to browse and use a website?  Is there an answer for why the way we interact with
-browsers when writing code is 100% different than the we do when writing a test?
-
-Brut cannot answer these things, but it does provide a way to write end-to-end tests with a browser, with
-a somewhat slightly reduced amount of pain.
-
-## Overview
-
-Brut uses [Playwright](https://playwright.dev/) and the
-[playwright-ruby-client](https://playwright-ruby-client.vercel.app/) to allow you to write end-to-end
-tests that use a web browser.  Brut sets up headless Chromium to do this.
-
-You can run End-to-End (e2e) tests with `bin/test e2e`.  You must use this to run individual tests as
-well, since this will ensure proper set up for the tests, which is more than is needed for a normal unit
-test.
-
-### Using Playwright
-
-At a high level, e2e tests look like normal RSpec tests:
-
-```ruby
-require "spec_helper"
-
-RSpec.describe "logging into the website" do
-
-  # ...
-
-end
-```
-
-The contents of your `it` blocks will use `playwright-ruby-client` to interact with the browser and make
-assertions.  The value `page` is available to use this API.
-
-```ruby
-require "spec_helper"
-
-RSpec.describe "logging into the website" do
-  it "shows an error when login is invalid" do
-    page.goto("/")
-
-    email     = page.locator("form input[type='email']")
-    password  = page.locator("form input[type='password']")
-    button    = page.locator("form button")
-
-    email.fill("pat@example.com")
-    password.fill("12345678")
-    button.click
-
-    flash = page.locator("[role='alert']")
-    expect(flash).to have_text("No email/password in our system")
-  end
-end
-```
-
-`playwright-ruby-client` provides excellent documentation on how it has adapted Playwright's API for use
-in Ruby.
-
-### Test Setup
-
-Brut will run your app via `Brut::SpecSupport::E2ETestServer`.  It will run it before the first e2e test, leave it running during the remainder of the test suite, then stop it. This means that database changes your test makes will persist across tests.
-
-If you are using Sidekiq, Sidekiq will be set up like normal. Jobs queued will go to Redis, and those jobs
-will be processed by Sidekiq, just like in production.  Thus, you should not assert things about specific
-jobs, but rather assert the effects those jobs will have. Redis is flushed between each test.
-
-### Test Helpers and Configuration
-
-Inside your test, `t` is available to produce translations. You can also access all your page and handler classes, so you can (and should) use `.routing`, e.g. `DashboardPage.routing`, to generate or access routes for your app.
-
-You can set the `e2e_timeout` metadata on any test to override the default amount of time Playwright will wait for a
-locator to locate an element. The default is 5 seconds.
-
-```ruby
-RSpec.describe "Test for login", e2e_timeout: 10 do
-  # ...
-end
-```
-
-You can also configure behavior with environment variables:
-
-| Variable            | Default | Purpose                                                                                           |
-|---------------------|---------|---------------------------------------------------------------------------------------------------|
-| `E2E_TIMEOUT_MS`    | 5000    | Number of milliseconds Playwright will wait for a locator to appear                               |
-| `E2E_SLOW_MO`       | 0       | Number of milliseconds Playwright will pause between operations. Useful to detect race conditions |
-| `E2E_RECORD_VIDEOS` | unset   | If set, videos of each test run are saved in `tmp/e2e-videos`                                     |
-
-
-### Quirks of Playwright
-
-The Playwright JavaScript API is heavily asycnhronous, requiring liberal use of `await`. The
-`playwright-ruby-client` wrapper abstracts that so you can write more straightfoward code.
-
-The main thing to be aware of is that locators that fail only fail when you attempt to assert something.
-
-For example
-
-```ruby
-button = page.locator("form button") # suppose this button doesn't exist
-
-button.click # This is where you'll see a failure
-```
-
-This hidden asynchronous behavior also means that certain calls will wait a period of time for the element
-you are locating to appear.  This is why the example test above works without having to explicitly wait
-for a page refresh.  After `button.click`, presumably the back-end is contacted and the page is
-re-rendered with an error.  As long as that happens within a second or so, the code will wait for an
-element matching `[role='alert']` to show up.
-
-## Recommended Practices
-
-E2e tests are slow. They can also be flaky if you aren't careful in how you write them and how you
-author your HTML.
-
-### Test Major Flows, Not Exhaustive Branches
-
-E2e tests give the most value when they assert that a sequence of actions the visitor takes result in what
-you expect—a "major flow".  Testing some error cases can be useful, but you should not use e2e tests to
-assert every single possible thing that could happen on a page.
-
-In fact, your app might be better off leaving some behaviors better untested instead of tested by an e2e test.  Use your judgement and be aware of the carrying cost of each e2e test.
-
-### Use CSS Selectors
-
-The main Playwright documentation encourages you to locate elements by "accessible names" and other
-indirect ways of finding elements.  In practice, this is error prone and tedious.  Determining the
-accessible name of an element is not always easy.
-
-We recommend you assess your app's accessibility in another way than trying to do it while performing end-to-end tests.  Instead, locate elements with CSS selectors—this is what you'd use to debug your app so it makes sense as a testing technique.
-
-Insulating your end-to-end tests from markup changes does not produce significant savings and can make tests more difficult to write.
-
-### Testing Must Inform your HTML
-
-To allow CSS selectors to survive minor changes to a page, your HTML should be authored with testing in
-mind.  In the example above, we locate the flash by looking for `[role='alert']`, since this is the most
-semantically correct way to mark up a flash message that contains an error.
-
-ARIA roles that should be applied for accessibility purposes can be leveraged as locators, as can custom
-elements.  Remember that any custom element is valid, even if it has no associated JavaScript.  Custom
-elements are an excellent way to "tag" markup for use in tests or progressively-enhanced behavior.
-
-CSS classes, on the other hand, are not a good candidate for identifying markup in a test. CSS classes
-exist to afford visual styling of elements and are the most likely to change as the app evolves.  A better
-fallback if there is no other way to locate an element is to use `data-testid`.  It makes itself painfully
-clear why it's there.  Use this sparingly, but it's there if you need it.
-
-### Asserting the Lack of Content Basically Doesn't Work
-
-To assert that some content or an element **is not** on the page requires locating it and waiting the
-timeout for that locate to fail. This sucks. Don't do it.
-
-If you need to assert that something did not happen, you may want to design your page or app such that
-markup appears that indicates whatever it is didn't happen.  This is not ideal, but a web page is a living
-thing that never stops changing, so your test can't just assume it's all synchronous.
-
-### Try to Use the Defaults for Timeouts
-
-Your app should not take 5 seconds to do anythning, especially not inside a test.  You may need to bump up
-the timeout to figure out what's going wrong, or set `E2E_SLOW_MO` to watch a video test, but once you've
-sorted out the issue, restore these to their defaults.
-
-If you *must* set `e2e_timeout` as metadata on test, **explain why** and try removing it every so often to
-make sure it's still needed.
-
-## Technical Notes
-
-> [!IMPORTANT]
-> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
-> internals, the source code is always more correct.
-
-_Last Updated June 13, 2025_
-
-The test server is run via `bin/test-server`.

data/brutrb.com/features.md

@@ -1,373 +0,0 @@
-# Quick Tour of Brut's Features
-
-## Pages
-
-A [*Page*](/pages) models, well, a web page. It's a class that holds all the data
-necessary to generate its HTML as well as a method called `page_template`, which
-generates the HTML via Phlex.
-
-A page's routing is convention-based and starts with a URL:
-
-```ruby{6}
-class App < Brut::Framework::App
-  def id           = "my-app"
-  def organization = "my-org"
-
-  routes do
-    page "/dashboard"
-  end
-end
-```
-
-This URL means our page class is expected in `DashboardPage`.
-
-```ruby
-class DashboardPage < AppPage
-  def initialize
-    @now     = Time.now
-  end
-
-  def page_template
-    main do
-     h1 { "Hello!" }
-     h2 do
-       plain("It's ")
-       time(datetime: l(@now, format: iso_8601)) do
-         l(@now, format: date)
-       end
-     end
-    end
-  end
-end
-```
-
-This would all produce HTML like so, depending on the value of 
-
-```html [/dashboard]
-<main>
-  <h1>Hello!</h1>
-  <h2>It's
-    <time datetime="2025-02-17">
-      Monday, Feb 17
-    </time>
-  </h2>
-</main>
-```
-
-Note that the actual HTML delivered would include the code for a layout.
-
-## Layouts
-
-Brut includes the concept of [layouts](/layouts), and they work similar to Rails.
-Layouts are classes, however, and implement the Phlex-standard `view_template`
-method:
-
-```ruby
-class DefaultLayout < Brut::FrontEnd::Layout
-  def initialize(page_name:)
-    @page_name = page_name
-  end
-
-  def view_template
-    doctype
-    html(lang: "en") do
-      head do
-        meta(charset: "utf-8")
-        link(rel: "preload", as: "style", href: asset_path("/css/styles.css"))
-        link(rel: "stylesheet",           href: asset_path("/css/styles.css"))
-        script(defer: true, src: asset_path("/js/app.js"))
-        title { app_name }
-      end
-      body do
-        yield
-      end
-    end
-  end
-end
-```
-
-This produces this HTML:
-
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <link rel="preload" as="style" href="/css/styles-«HASH».css">
-    <link rel="stylesheet" href="/css/styles-«HASH».css">
-    <script defer src="/js/app-«HASH».js">
-    <title>My Awesome App</title>
-  </head>
-  <body>
-    <-- page HTML here -->
-  </body>
-</html>
-```
-
-
-## Components
-
-*Components* are a way to manage the complexity of HTML generation. The are Phlex components, meaning they are a class that implements `view_template`.
-
-Here's an example of a flash message component:
-
-```ruby
-# components/flash_component.rb
-class FlashComponent < AppComponent
-  def initialize(flash:)
-    if flash.notice?
-      @message_key = flash.notice
-      @role = :info
-    elsif flash.alert?
-      @message_key = flash.alert
-      @role = :alert
-    end
-  end
-
-  def any_message? = !@message_key.nil?
-
-  def view_template
-    if any_message?
-      div(role: @role) do
-        t([ :flash, @message_key ])
-      end
-    end
-  end
-end
-```
-
-You can then use this in any other view using `render`, provided by Phlex.
-
-```ruby
-def page_template
-  header do
-    render FlashComponent.new(flash:)
-  end
-end
-```
-
-## Forms
-
-[*Forms*](/forms) are a major concept like pages, since they are the way a browser
-submits data to the server.
-
-In Brut, a form does three things:
-
-* Describes the data in the `<form>` tag
-* Implies a route where its data is submitted via HTTP POST
-* Provides access to the submitted data (via an object with methods, not a Hash of Whatever)
-
-Like `page`, `form` declares a form's route:
-
-```ruby{2}
-routes do
-  form "/login"
-end
-```
-
-Brut is convention-based, so it will expect a class named `LoginForm` to exist. It
-will also expect `LoginHandler` to exist, which is a class that will receive the
-form submission and process it. More on handlers below.
-
-`LoginForm` uses class methods to declare its inputs.  These class methods mirror
-the various form element tags in HTML (`input`, `select`, etc.), and the methods
-attributes allow you to declare names and client-side constraints:
-
-```ruby [forms/login_form.rb]
-class LoginForm < AppForm
-  input :email
-  input :password, minlength: 8
-end
-```
-
-An instance of this class can be used to create HTML:
-
-```ruby
-def view_template
-  FormTag(for: @form) do
-    Inputs::InputTag(form: @form, input_name: :email)
-    Inputs::InputTag(form: @form, input_name: :password)
-    button { "Login" }
-  end
-end
-```
-
-> [!NOTE]
-> We'll explain what `FormTag` and `Inputs::InputTag` are in the [forms
-> section](/forms)
-
-This generates this HTML:
-
-```html
-<form action="/login" method="POST">
-  <input type="email" name="email" required>
-  <input type="password" name="password" required minlength="8">
-  <button>Login</button>
-</form>
-```
-
-When the form is submitted, an instance of `LoginForm` is created and made available
-to `LoginHandler`
-
-## Handlers
-
-A handler is like a controller in Rails, except it only has one method: `handle`.
-Unlike a Rails controller, a handler class is given its arguments explicitly, and
-`handle`'s return value dictates what will happen next.
-
-```ruby
-class LoginHandler < AppHandler
-  def initialize(form:)
-    @form = form
-  end
-  def handle
-    if @form.email == "secret@example.com" &&
-       @form.password = "sup3rs3cret!"
-       redirect_to(DashboardPage)
-    else
-      form.server_side_constraint_violation(
-        input_name: :email,
-        key: :no_such_user
-      )
-      LoginPage.new(form:)
-    end
-  end
-end
-```
-
-Note that we access the form's values as methods, not by digging into a Hash of
-Whatever.  Also note that returning an instance of a page will generate that page's
-HTML, much like Rails' `render :edit` might.  Lastly, `redirect_to` is a
-convenience to generate a URL to `DashboardPage`, and ultimately causes `handle` to
-return a `URI`, which Brut interprets as a redirect.
-
-
-## JavaScript
-
-Brut doesn't include a front-end framework, however you can certainly use one.  All
-JavaScript is bundled into a single bundle by [esbuild](https://esbuild.github.io/).
-
-Brut includes [BrutJS](/brut-js), which is a collection of autonomous custom
-elements AKA Web Components that provide convenient features like autosubmit, form
-submission confirmation and more:
-
-```ruby{5,7}
-def view_template
-  FormTag(for: @form) do
-    Inputs::InputTag(form: @form, input_name: :email)
-    Inputs::InputTag(form: @form, input_name: :password)
-    brut_confirm_submit(message: "Really login? In this economy?!") do
-      button { "Login" }
-    end
-  end
-end
-```
-
-When "Login" is pressed, `window.confirm` will ask if the visitor wants to proceed.
-This custom element can also use a `<dialog>` that you style, and works even better
-if that `<dialog>` makes use of `<brut-confirmation-dialog>`.
-
-## CSS
-
-Brut includes [BrutCSS](/css#using-brut-css), which is a lightweight utility-based
-CSS library to let you get started quickly. It's *not* TailwindCSS, nor will it ever
-be.
-
-You can replace it with whatever you like easily enough.
-
-
-## Database Schema
-
-Brut provides access to an SQL database via Sequel.  Brut uses Sequel's database schema management, however it is enhanced to
-encourage good practices by default.
-
-> [!NOTE]
-> Brut currently *only supports* PostgreSQL.  It may support all RDBMSes that Sequel supports, but as of now,
-> it's just Postgres.
-
-Consider a `households` table that relates to an `accounts` table.
-
-```ruby
-create_table :households,
-             comment: "Family unit managing the data" do
-  column :timezone, :text
-  column :dinner_time_of_day, :text
-  constraint(
-    :time_must_be_time,
-    %{
-      (dinner_time_of_day ~ '^[01][0-9]:[0-5][0-9]$') OR
-      (dinner_time_of_day ~ '^2[0-3]:[0-5][0-9]$')
-    }
-  )
-end
-
-create_table :accounts,
-             comment: "People or systems who can access this system",
-             external_id: true do
-
-  column :email,             :email_address, unique: true
-  column :deactivated_at,    :timestamptz, null: true
-  foreign_key :household_id, :households
-end
-```
-
-This is mostly using [Sequel's built-in migrations API](https://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html).  But, a few additional behaviors are happening:
-
-* Columns default to `NOT NULL`
-* Tables require comments
-* Foreign keys default to having constraints and indexes
-
-There are other quality-of-life features of Brut's migration system, all designed to default to a good practice, with a way to do it
-however you want when needed.
-
-## Database Access
-
-Brut uses `Sequel::Model` to access data in your database.  To discourage the conflation of "models of database tables" with "models
-of your application's domain", these classes are in the `DB` namespace.  Thus, the class `DB::Household` would be able to access the
-`households` table defined above. This frees you up to create a `Household` class to model your domain's logic without being coupled
-to how you store some data in a database.
-
-```ruby
-class DB::Account < AppDataModel
-  has_external_id :ac
-  many_to_one :household
-end
-
-class DB::Household < AppDataModel
-  one_to_many :accounts
-end
-```
-
-## Domain and Business Logic
-
-Brut uses Zeitwerk for code loading, so any directories you create will be auto-loaded and refreshed during development.  This means that you can create a class named `Household` in `app/src/back_end/domain/household.rb` and it would be loaded.  Or, you could create `HouseholdService` in `app/src/back_end/services/household_service.rb` if you like.
-
-> [!TIP]
-> Providing a generally-useful abstraction for business or domain logic is not usually feasible.
-> Thus, Brut doesn't provide much beyond Zeitwerk's auto-loading feature.  It may provide more
-> assistance in  the future, but for now, Brut's approach is to free you from any prescription
-> or moral imperative. Manage your domain and business logic how you see fit. You know your domain
-> and team better than we do.
-
-## Testing
-
-Brut provides support for three types of tests:
-
-* Unit Tests, using RSpec
-* End-to-end tests, using RSpec and Playwright
-* Custom Element tests, written in JavaScript, using Mocha
-
-Since Brut is based on classes, objects, and methods, your unit tests will usually
-be straightforward, however Brut provides helpers to test your Page and Component
-HTML using Nokogiri.  FactoryBot is included and configured to manage test data.
-
-## Tasks
-
-Brut doesn't use Rake tasks. It uses CLI apps powered by Ruby's `OptionParser`.  Brut provides bootstrapping classes to make your own CLIs, as well as some light abstractions to make `OptionParser` a little more ergonomic.  Brut's dev and production management CLIs are built using this support.
-
-## Observability
-
-Brut has built-in support for [OpenTelemetry](https://opentelemetry.io/).  Brut includes configuration for the [otel-desktop-viewer](https://github.com/CtrlSpice/otel-desktop-viewer) or a text-based viewer suitable for development.  For production, most observability vendors provide OpenTelemetry ingestion any many have free tiers.
-
-Brut does support logging, however you are encouraged to use OpenTelemetry instead.
-