data_porter 0.1.0

data/docs/blog/013-testing-rails-engine.md

@@ -0,0 +1,618 @@
+---
+title: "Building DataPorter #13 -- Testing a Rails Engine with RSpec"
+series: "Building DataPorter - A Data Import Engine for Rails"
+part: 13
+tags: [ruby, rails, rails-engine, gem-development, rspec, testing, tdd]
+published: false
+---
+
+# Testing a Rails Engine with RSpec
+
+> How to test a mountable Rails engine without a full Rails app -- using an in-memory SQLite database, stub controllers, anonymous target classes, and a spec_helper that bootstraps just enough Rails to exercise ActiveRecord, StoreModel, Phlex, generators, and even JavaScript files.
+
+## Context
+
+This is part 13 of the series where we build **DataPorter**, a mountable Rails engine for data import workflows. In [part 12](#), we extended the Source layer to support JSON files and API endpoints.
+
+We have been writing specs throughout the series, but we never stepped back to explain *how* the test suite works. A Rails engine is not a Rails app. There is no `config/database.yml`. There is no `spec/rails_helper.rb` generated by `rspec-rails`. There is no schema to load, no test database to create, no `ApplicationController` to inherit from. Every piece of infrastructure that a typical Rails project gives you for free -- the database connection, the load paths, the base controller class -- has to be set up manually in a gem's test suite.
+
+In this article, we look at the full testing strategy: the spec_helper that bootstraps a minimal Rails environment, the patterns we use for each layer (models, controllers, components, generators, JavaScript), and the TDD workflow that shaped the series.
+
+## The problem
+
+A Rails engine gem ships as a library. It has no `bin/rails`, no `config/application.rb`, no running server. When you run `rspec` inside the gem, Ruby loads your `spec_helper.rb` and your spec files -- and that is it. If your code depends on ActiveRecord, you need a database. If it depends on ActionController, you need a controller base class. If it depends on load paths for `app/models` or `app/controllers`, you need to set those up yourself.
+
+The conventional solution is a "dummy app" -- a minimal Rails application inside `spec/dummy/` that boots the full Rails stack, mounts the engine, and provides the infrastructure specs need. This works, but it comes with overhead: you maintain a separate `Gemfile.lock`, a database config, an application class, route files, and all the boilerplate of a Rails app that exists only for tests. When the engine is small and focused, that overhead feels disproportionate.
+
+DataPorter takes a different approach: no dummy app. The `spec_helper.rb` bootstraps just enough Rails to make the specs work, and nothing more. No application class. No route loading. No middleware stack. Just the frameworks we actually use -- ActiveRecord, ActiveJob, ActionController, ActionCable -- configured at the minimum viable level.
+
+## What we're building
+
+Here is the spec_helper that powers the entire test suite:
+
+```ruby
+# spec/spec_helper.rb
+require "rails"
+require "active_record"
+require "active_job"
+require "action_controller"
+require "action_cable"
+require "data_porter"
+
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: ":memory:"
+)
+
+ActiveRecord::Schema.define do
+  create_table :data_porter_imports, force: true do |t|
+    t.string  :target_key,  null: false, default: ""
+    t.string  :source_type, null: false, default: "csv"
+    t.integer :status,      null: false, default: 0
+    t.text    :records
+    t.text    :report
+    t.text    :config
+
+    t.string  :user_type
+    t.integer :user_id
+
+    t.timestamps
+  end
+end
+
+%w[models jobs].each do |dir|
+  $LOAD_PATH.unshift File.expand_path("../app/#{dir}", __dir__)
+end
+require "data_porter/data_import"
+require "data_porter/parse_job"
+require "data_porter/import_job"
+
+# Stub for controller inheritance in test context
+class ApplicationController < ActionController::Base; end unless defined?(ApplicationController)
+
+$LOAD_PATH.unshift File.expand_path("../app/controllers", __dir__)
+require "data_porter/imports_controller"
+
+$LOAD_PATH.unshift File.expand_path("../app/channels", __dir__)
+require "data_porter/import_channel"
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end
+```
+
+Sixty lines of setup that replace a 200-file dummy app. Every line exists because a spec somewhere needs it.
+
+## Implementation
+
+### Step 1 -- The in-memory database
+
+The first problem is the database. DataPorter's `DataImport` model is an ActiveRecord class that needs a real table with real columns. In a Rails app, you would run `rails db:create db:migrate`. In a gem, there is no migration runner. We need to create the schema from scratch every time the specs run.
+
+SQLite's `:memory:` database solves this perfectly:
+
+```ruby
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: ":memory:"
+)
+
+ActiveRecord::Schema.define do
+  create_table :data_porter_imports, force: true do |t|
+    t.string  :target_key,  null: false, default: ""
+    t.string  :source_type, null: false, default: "csv"
+    t.integer :status,      null: false, default: 0
+    t.text    :records
+    t.text    :report
+    t.text    :config
+    t.string  :user_type
+    t.integer :user_id
+    t.timestamps
+  end
+end
+```
+
+The `establish_connection` call creates a SQLite database that lives entirely in memory -- no file on disk, no cleanup needed, no state leaking between test runs. The `Schema.define` block creates the table immediately. By the time the first spec runs, the database exists with the right schema.
+
+The schema here mirrors the migration that the install generator creates for host apps, but it is defined inline rather than loaded from a migration file. This is a deliberate duplication: the spec_helper schema is the *test contract*, not the migration itself. If the migration changes and we forget to update the spec_helper, a spec will fail -- which is exactly the signal we want.
+
+The `text` columns for `records`, `report`, and `config` are where StoreModel does its work. In production with PostgreSQL, these would be `jsonb` columns. In the test suite with SQLite, they are `text` columns -- and StoreModel handles the serialization transparently in both cases. This is one of the advantages of StoreModel over raw JSONB: the serialization adapter abstracts the column type difference.
+
+### Step 2 -- Load paths and the ApplicationController stub
+
+A Rails engine's code lives in `app/models`, `app/controllers`, `app/jobs`, and `app/channels`. In a running Rails app, the autoloader resolves these paths. In a gem's test suite, there is no autoloader. We add the directories to `$LOAD_PATH` manually:
+
+```ruby
+%w[models jobs].each do |dir|
+  $LOAD_PATH.unshift File.expand_path("../app/#{dir}", __dir__)
+end
+require "data_porter/data_import"
+require "data_porter/parse_job"
+require "data_porter/import_job"
+```
+
+This is straightforward but easy to forget: without the `$LOAD_PATH` manipulation, `require "data_porter/data_import"` would fail because Ruby does not know to look in `app/models`.
+
+The controller layer is trickier. `ImportsController` inherits from the host app's `ApplicationController` (or whatever `DataPorter.configuration.parent_controller` is set to). In a host Rails app, that class already exists. In the gem's test suite, it does not. We stub it:
+
+```ruby
+class ApplicationController < ActionController::Base; end unless defined?(ApplicationController)
+```
+
+The `unless defined?` guard is important. If something else in the test environment has already defined `ApplicationController` (which happens in some CI setups), we do not want to redefine it. The stub gives us just enough to verify that `ImportsController` is loadable, inherits from the right parent, and defines the expected methods. It does not give us routing or request processing -- but we do not need those for the kind of controller testing we do, which we will cover shortly.
+
+### Step 3 -- Testing ActiveRecord models with StoreModel
+
+The `DataImport` model is a standard ActiveRecord class that uses StoreModel for its `records`, `report`, and `config` attributes. Testing it requires a working database (which we set up in step 1) and the StoreModel gem loaded (which happens through the `require "data_porter"` in the spec_helper).
+
+The model specs test what any model spec would: validations, enum behavior, default values, and persistence. Here is the pattern:
+
+```ruby
+# spec/data_porter/data_import_spec.rb
+RSpec.describe DataPorter::DataImport, type: :model do
+  let(:target_class) do
+    Class.new(DataPorter::Target) do
+      label "Guests"
+      model_name "Guest"
+      icon "fas fa-users"
+    end
+  end
+
+  before do
+    DataPorter::Registry.clear
+    DataPorter::Registry.register(:guests, target_class)
+  end
+
+  describe "validations" do
+    it "requires target_key" do
+      import = described_class.new(source_type: "csv")
+
+      expect(import).not_to be_valid
+      expect(import.errors[:target_key]).to include("can't be blank")
+    end
+  end
+
+  describe "persistence" do
+    it "saves and reloads with records" do
+      import = described_class.create!(
+        target_key: "guests",
+        source_type: "csv",
+        user_type: "User",
+        user_id: 1
+      )
+      record = DataPorter::StoreModels::ImportRecord.new(
+        line_number: 1,
+        data: { name: "Alice" }
+      )
+      import.update!(records: [record])
+
+      reloaded = described_class.find(import.id)
+
+      expect(reloaded.records.first.line_number).to eq(1)
+      expect(reloaded.records.first.data).to eq({ "name" => "Alice" })
+    end
+  end
+end
+```
+
+Two things stand out. First, every spec that depends on a target class creates an **anonymous class** with `Class.new(DataPorter::Target)` and registers it in the `before` block. This avoids polluting the global namespace with named test classes and ensures each spec controls its own target definition. The `Registry.clear` in `before` prevents target registrations from one spec leaking into another.
+
+Second, the persistence spec exercises the full StoreModel round-trip: create a DataImport, add ImportRecord objects to the `records` attribute, save, reload from the database, and verify the data survived serialization. This is critical because StoreModel serializes to JSON under the hood, and the round-trip through SQLite's `text` column can surface subtle issues -- symbol keys becoming string keys, for instance, which is exactly what `{ "name" => "Alice" }` (not `{ name: "Alice" }`) is testing.
+
+### Step 4 -- Testing StoreModel objects in isolation
+
+The `ImportRecord` is a StoreModel type, not an ActiveRecord model. It has no table. It exists as a JSONB-backed object inside a `DataImport`'s `records` array. Testing it does not require a database at all:
+
+```ruby
+# spec/data_porter/store_models/import_record_spec.rb
+RSpec.describe DataPorter::StoreModels::ImportRecord do
+  subject(:record) { described_class.new(line_number: 1, data: { name: "Alice" }) }
+
+  describe "#add_error" do
+    it "appends an error to errors_list" do
+      record.add_error("name is required")
+
+      expect(record.errors_list.size).to eq(1)
+      expect(record.errors_list.first.message).to eq("name is required")
+    end
+  end
+
+  describe "#determine_status!" do
+    it "sets complete when no errors" do
+      record.determine_status!
+
+      expect(record.status).to eq("complete")
+    end
+
+    it "sets missing when required field error exists" do
+      record.add_error("Name is required")
+      record.determine_status!
+
+      expect(record.status).to eq("missing")
+    end
+  end
+
+  describe "#attributes" do
+    it "returns symbolized compact data" do
+      record = described_class.new(data: { "name" => "Alice", "email" => nil })
+
+      expect(record.attributes).to eq({ name: "Alice" })
+    end
+  end
+end
+```
+
+StoreModel objects behave like plain Ruby objects with attribute accessors -- you instantiate them with a hash, call methods on them, and assert on their state. No database queries, no fixtures, no setup. The `#attributes` spec is particularly important because it verifies the `compact` and `symbolize_keys` behavior that downstream code (the target's `persist` method) depends on. If `attributes` returned `nil` values or string keys, persisting to the host app's models would fail in subtle ways.
+
+### Step 5 -- Testing controllers structurally
+
+In a full Rails app, you would test controllers with request specs: send a POST, check the response status, verify the redirect. In a gem without a dummy app, there is no router, no middleware stack, and no request processing. We cannot send HTTP requests because there is nowhere to send them.
+
+Instead, we test controllers *structurally* -- verifying the class hierarchy, the callback registrations, and the method signatures:
+
+```ruby
+# spec/data_porter/imports_controller_spec.rb
+RSpec.describe DataPorter::ImportsController do
+  describe "inheritance" do
+    it "inherits from the configured parent controller" do
+      expect(described_class.superclass.name).to eq(
+        DataPorter.configuration.parent_controller
+      )
+    end
+  end
+
+  describe "before_actions" do
+    it "registers set_import callback" do
+      callbacks = described_class._process_action_callbacks.select do |c|
+        c.filter == :set_import
+      end
+
+      expect(callbacks).not_to be_empty
+    end
+  end
+
+  describe "action methods" do
+    it "defines index, new, create, show, parse, confirm, and cancel" do
+      actions = %i[index new create show parse confirm cancel]
+      actions.each do |action|
+        expect(described_class.instance_method(action)).to be_a(UnboundMethod)
+      end
+    end
+  end
+
+  describe "private methods" do
+    it "defines set_import" do
+      expect(described_class.private_instance_methods).to include(:set_import)
+    end
+
+    it "defines import_params" do
+      expect(described_class.private_instance_methods).to include(:import_params)
+    end
+  end
+end
+```
+
+This approach tests four things that matter at the gem level: (1) the controller inherits from the right parent class, which proves the dynamic inheritance mechanism works; (2) the `before_action` callbacks are registered, which proves the controller's lifecycle is set up correctly; (3) every expected action method exists as an instance method; (4) the private helper methods exist and are private.
+
+What this does *not* test is the actual behavior of those actions -- what happens when you call `create` with certain params, or whether `show` renders the right component. Those are integration concerns that belong in the host app's test suite, or in a separate integration test suite with a dummy app. The gem-level specs verify the *contract* -- the controller exists, has the right shape, and plugs into the right place. The host app tests verify the *behavior*.
+
+The `_process_action_callbacks` API is an internal Rails method that returns the registered callbacks. It is not a public API, but it is stable across Rails versions and it is the only way to verify callback registration without actually processing a request. Using it here is a pragmatic choice -- the alternative is a full request spec, which requires a dummy app.
+
+### Step 6 -- Testing Phlex components
+
+Phlex components are the easiest layer to test in a gem context because they have zero Rails dependencies. A Phlex component is a Ruby object with a `call` method that returns an HTML string. No view context, no request, no controller:
+
+```ruby
+# spec/data_porter/components/preview_table_spec.rb
+RSpec.describe DataPorter::Components::PreviewTable do
+  def render(component)
+    component.call
+  end
+
+  let(:target_class) do
+    Class.new(DataPorter::Target) do
+      label "Guests"
+      model_name "Guest"
+
+      columns do
+        column :first_name, type: :string, required: true
+        column :last_name, type: :string
+      end
+    end
+  end
+
+  let(:record) do
+    DataPorter::StoreModels::ImportRecord.new(
+      line_number: 1,
+      status: "complete",
+      data: { "first_name" => "Alice", "last_name" => "Smith" }
+    )
+  end
+
+  let(:error_record) do
+    r = DataPorter::StoreModels::ImportRecord.new(
+      line_number: 2,
+      status: "missing",
+      data: { "first_name" => "", "last_name" => "Jones" }
+    )
+    r.add_error("First name is required")
+    r
+  end
+
+  it "renders column headers from target" do
+    html = render(described_class.new(columns: target_class._columns, records: [record]))
+
+    expect(html).to include("First name")
+    expect(html).to include("Last name")
+  end
+
+  it "renders error messages" do
+    html = render(described_class.new(columns: target_class._columns, records: [error_record]))
+
+    expect(html).to include("First name is required")
+  end
+
+  it "includes status-specific row class" do
+    html = render(described_class.new(columns: target_class._columns, records: [record]))
+    expect(html).to include("dp-row--complete")
+  end
+end
+```
+
+The local `render` helper is just `component.call` -- but giving it a name makes the specs read like a sentence: "render the component, expect the html to include this string." Every component spec follows this exact pattern.
+
+The PreviewTable spec is the most interesting because it tests the full chain: the anonymous Target class declares columns via the DSL, those columns are passed to the component, and the rendered HTML includes the column labels and record data. This exercises the integration between the Target DSL and the view layer without touching a database.
+
+The assertions are string-based (`include("Alice")`) rather than DOM-based (`have_css("td", text: "Alice")`). We do not use Capybara or Nokogiri for component specs. String matching is sufficient for verifying that the right content appears in the output, and it keeps the test dependencies minimal. For a gem that ships UI components, the host app's integration tests are the place for DOM-level assertions.
+
+### Step 7 -- Testing generators
+
+Generator testing in a gem without a dummy app requires a different approach from the usual `rails generate` flow. We cannot run the generator and check the filesystem output because the generator expects a Rails app directory structure. Instead, we test the generator class itself -- its inheritance, its source root, and its method definitions:
+
+```ruby
+# spec/data_porter/generators/install_generator_spec.rb
+require "generators/data_porter/install/install_generator"
+
+RSpec.describe DataPorter::Generators::InstallGenerator do
+  it "inherits from Rails::Generators::Base" do
+    expect(described_class.superclass).to eq(Rails::Generators::Base)
+  end
+
+  it "has a source_root pointing to templates" do
+    expect(described_class.source_root).to end_with(
+      "lib/generators/data_porter/install/templates"
+    )
+  end
+
+  describe "generator methods" do
+    it "defines copy_migration" do
+      expect(described_class.instance_method(:copy_migration)).to be_a(UnboundMethod)
+    end
+
+    it "defines copy_initializer" do
+      expect(described_class.instance_method(:copy_initializer)).to be_a(UnboundMethod)
+    end
+
+    it "defines create_importers_directory" do
+      expect(described_class.instance_method(:create_importers_directory)).to be_a(UnboundMethod)
+    end
+
+    it "defines mount_engine" do
+      expect(described_class.instance_method(:mount_engine)).to be_a(UnboundMethod)
+    end
+  end
+end
+```
+
+The `require` at the top loads the generator file directly from the `lib/generators` path -- it does not use the Rails generator lookup mechanism. The specs then verify three things: the generator inherits from the right base class (which determines what helpers are available), the `source_root` points to the right template directory (which determines where template files are found during generation), and every expected generator method exists (which determines what the generator actually does when invoked).
+
+This is the same structural testing pattern we use for controllers. The specs prove the generator *exists and is wired correctly*. They do not prove that running `rails generate data_porter:install` produces the right files -- that would require a dummy app with a writable filesystem. But they catch the most common generator bugs: a misspelled method name, a wrong source root, or a missing base class.
+
+### Step 8 -- Testing JavaScript from Ruby specs
+
+DataPorter ships a Stimulus controller in `app/javascript/data_porter/progress_controller.js`. In a typical frontend project, you would test this with Jest or Vitest, running the JavaScript in a Node.js environment. But DataPorter is a Ruby gem. Adding a JavaScript test runner means adding `package.json`, `node_modules`, and a separate CI step. For a single 30-line Stimulus controller, that is a lot of overhead.
+
+Instead, we test the JavaScript file as a *text artifact* from Ruby:
+
+```ruby
+# spec/data_porter/progress_controller_js_spec.rb
+RSpec.describe "progress_controller.js" do
+  let(:js_path) do
+    File.expand_path("../../app/javascript/data_porter/progress_controller.js", __dir__)
+  end
+  let(:content) { File.read(js_path) }
+
+  it "exists" do
+    expect(File.exist?(js_path)).to be true
+  end
+
+  it "imports Stimulus Controller" do
+    expect(content).to include('import { Controller } from "@hotwired/stimulus"')
+  end
+
+  it "imports ActionCable consumer" do
+    expect(content).to include('import { createConsumer } from "@rails/actioncable"')
+  end
+
+  it "defines bar and text targets" do
+    expect(content).to include('static targets = ["bar", "text"]')
+  end
+
+  it "defines id value" do
+    expect(content).to include("static values = { id: Number }")
+  end
+
+  it "subscribes to ImportChannel on connect" do
+    expect(content).to include("DataPorter::ImportChannel")
+  end
+
+  it "unsubscribes on disconnect" do
+    expect(content).to include("this.subscription?.unsubscribe()")
+  end
+
+  it "updates progress bar width and text" do
+    expect(content).to include("this.barTarget.style.width")
+    expect(content).to include("this.textTarget.textContent")
+  end
+end
+```
+
+This reads the JavaScript file as a string and asserts that it contains the expected patterns: the right imports, the right Stimulus static declarations, the right channel subscription, the right DOM updates. It does not execute the JavaScript. It does not test that the progress bar actually animates. It tests the *contract* between the JavaScript file and the rest of the system.
+
+This approach catches a specific class of bugs: someone renames the ActionCable channel in Ruby but forgets to update the JavaScript subscription string. Someone removes a Stimulus target from the HTML but leaves the target declaration in the controller. Someone refactors the progress update and forgets to update `barTarget.style.width`. These are integration seams where Ruby and JavaScript must agree, and string matching catches disagreements.
+
+Is this a substitute for real JavaScript testing? No. But for a Ruby gem with a single Stimulus controller, it provides meaningful coverage without adding a JavaScript toolchain to the project. If the Stimulus controller grows more complex, the calculus changes and a proper JS test runner becomes worth the overhead.
+
+### Step 9 -- The anonymous target class pattern
+
+A pattern that runs through nearly every spec file is the anonymous target class:
+
+```ruby
+let(:target_class) do
+  Class.new(DataPorter::Target) do
+    label "Guests"
+    model_name "Guest"
+    icon "fas fa-users"
+    sources :csv
+
+    columns do
+      column :first_name, type: :string, required: true
+      column :last_name, type: :string
+      column :email, type: :email
+    end
+
+    csv_mapping do
+      map "First Name" => :first_name
+      map "Last Name" => :last_name
+      map "Email" => :email
+    end
+
+    define_method(:persist) do |record, **|
+      records << record.data
+    end
+  end
+end
+```
+
+This creates a new class that inherits from `DataPorter::Target` without giving it a constant name. Each spec defines exactly the target it needs -- the Orchestrator spec defines one with `persist`, the CSV spec defines one with `csv_mapping`, the PreviewTable spec defines one with just `columns`. No spec depends on a shared target fixture that might change.
+
+The `define_method(:persist)` pattern (instead of `def persist`) is required because anonymous class blocks use `Class.new` with a block, and `def` inside that block defines a method on the class -- but if the method needs to capture a local variable (like `records` for the collection array), `define_method` with a closure is the only way. This is a Ruby metaprogramming detail that comes up often when testing DSL-heavy code.
+
+The companion pattern is registry cleanup:
+
+```ruby
+before do
+  DataPorter::Registry.clear
+  DataPorter::Registry.register(:guests, target_class)
+end
+
+after { DataPorter::Registry.clear }
+```
+
+Every spec that registers a target clears the registry before and after. Without this, target registrations accumulate across specs, leading to flaky tests where the order of execution matters. The `clear` method on the Registry exists primarily for this testing use case.
+
+## Decisions & tradeoffs
+
+| Decision | We chose | Over | Because |
+|----------|----------|------|---------|
+| Test infrastructure | Inline spec_helper with in-memory SQLite | Dummy Rails app in `spec/dummy/` | Less maintenance overhead, faster boot time, no separate Gemfile or config to maintain |
+| Controller testing | Structural tests (inheritance, callbacks, method existence) | Request specs with a dummy app | Verifies the contract without requiring routing, middleware, or a full request cycle |
+| Component testing | `component.call` with string assertions | Capybara or Nokogiri DOM assertions | Minimal dependencies; string matching is sufficient for verifying content in component output |
+| Generator testing | Class-level structural tests | Running the generator against a temp directory | Catches wiring bugs without requiring a writable Rails app filesystem |
+| JavaScript testing | Ruby string matching on file content | Jest/Vitest with a Node.js test runner | Avoids adding a JS toolchain for a single 30-line file; tests the Ruby/JS integration contract |
+| Target fixtures | Anonymous classes per spec with `Class.new` | Shared named target classes | Each spec controls its own target definition; no coupling between specs |
+| Registry isolation | `clear` before and after each spec that registers targets | Global shared state | Prevents registration leakage and ordering-dependent test failures |
+| StoreModel testing | Direct instantiation without database | Round-trip through ActiveRecord | StoreModel objects are plain Ruby objects; database round-trips are tested separately on the DataImport model |
+
+## Testing it
+
+The test suite itself is best verified by running it:
+
+```bash
+$ bundle exec rspec
+
+DataPorter::Configuration
+  has default parent_controller
+  has default queue_name
+  has default storage_service
+  ...
+
+DataPorter::DataImport
+  validations
+    requires target_key
+    requires source_type
+  enum status
+    defaults to pending
+  persistence
+    saves and reloads with records
+
+DataPorter::StoreModels::ImportRecord
+  #add_error
+    appends an error to errors_list
+  #determine_status!
+    sets complete when no errors
+    sets missing when required field error exists
+
+DataPorter::Orchestrator
+  #parse!
+    transitions to previewing
+    creates import records from source data
+    validates required fields
+  #import!
+    transitions to completed
+    handles per-record errors
+
+DataPorter::Components::PreviewTable
+  renders column headers from target
+  renders record data in rows
+  includes status-specific row class
+
+DataPorter::Generators::InstallGenerator
+  inherits from Rails::Generators::Base
+  has a source_root pointing to templates
+
+progress_controller.js
+  imports Stimulus Controller
+  defines bar and text targets
+  subscribes to ImportChannel on connect
+
+Finished in 0.XXs
+XX examples, 0 failures
+```
+
+Every layer of the engine has coverage. The in-memory database starts and tears down in milliseconds. The full suite runs in under a second.
+
+## The TDD workflow
+
+Throughout this series, every feature followed the same cycle: write a spec that describes the behavior we want, watch it fail, implement the minimum code to make it pass, then refactor. This is not a theoretical preference -- it is a practical necessity when building a gem.
+
+In a Rails app, you can spike code in a controller action, hit refresh in the browser, and see if it works. In a gem, there is no browser. The spec suite *is* the feedback loop. When we built the Orchestrator in part 7, the first thing we wrote was a spec that called `orchestrator.parse!` and expected `data_import.status` to be `"previewing"`. When we built the PreviewTable in part 9, the first thing we wrote was a spec that rendered the component with two columns and expected the HTML to include both column headers.
+
+The anonymous target class pattern emerged from this workflow. We needed a way to define targets inline in specs without creating named classes that would pollute the test namespace. `Class.new(DataPorter::Target)` was the answer, and it became the standard pattern for every spec that touches the target system.
+
+The structural controller testing pattern also emerged from necessity. We needed to verify that `ImportsController` inherits from the configured parent controller, but we had no router to send requests through. Instead of building a dummy app just for controller tests, we tested the class structure directly. This turned out to be more valuable than request specs anyway, because the structural tests verify the *engine's contribution* -- the inheritance, the callbacks, the method definitions -- while leaving the *integration behavior* to the host app.
+
+## Recap
+
+- **No dummy app**: the spec_helper bootstraps an in-memory SQLite database, sets up load paths, and stubs `ApplicationController` -- just enough Rails to test a full engine.
+- **StoreModel objects** are tested as plain Ruby objects, with database round-trip tests on the parent ActiveRecord model.
+- **Controllers** are tested structurally -- inheritance, callbacks, and method existence -- rather than with request specs, because the gem has no router.
+- **Phlex components** are tested by calling `.call` and asserting against the HTML string, with no view context or browser.
+- **Generators** are tested by verifying class hierarchy, source root, and method definitions -- the wiring, not the filesystem output.
+- **JavaScript files** are tested as text artifacts from Ruby, verifying the contract between the JS and the rest of the engine.
+- **Anonymous target classes** with `Class.new` keep each spec self-contained, and `Registry.clear` prevents state leakage.
+
+## Next up
+
+Now that we have a tested, fully-featured engine, there is one more safety net to add before imports touch the database. In part 14, we build **Dry Run** -- a validation mode that wraps the import in a transaction, rolls it back, and enriches records with the database-level errors that the preview phase cannot catch. Preview validates the *data*; dry run validates the *persistence*.
+
+---
+
+*This is part 13 of the series "Building DataPorter - A Data Import Engine for Rails". [Previous: Adding JSON & API Sources](#) | [Next: Dry Run: Validate Before You Persist](#)*