Getting Started Quick Start - hiraishikentaro/rails-factorybot-jump GitHub Wiki

Getting Started: Quick Start

Get the Rails FactoryBot Jump extension running in 5 minutes.

Installation

Option 1: VSCode Marketplace (Recommended)

  1. Open VSCode
  2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
  3. Search for "Rails FactoryBot Jump"
  4. Click "Install"

Option 2: Development Installation

# Clone and setup
git clone https://github.com/hiraishikentaro/rails-factorybot-jump.git
cd rails-factorybot-jump
npm install
npm run compile

# Launch in VSCode
code .
# Press F5 to start Extension Development Host

Basic Usage

1. Open a Rails Project

Ensure your project has:

  • FactoryBot setup
  • Factory files in spec/factories/ or test/factories/
  • Test files using FactoryBot

2. Test the Extension

Create or open a test file with FactoryBot calls:

# spec/models/user_spec.rb
RSpec.describe User do
  it "creates a user" do
    user = create(:user)  # ← This will be clickable
    expect(user).to be_valid
  end

  it "builds a user with admin trait" do
    admin = create(:user, :admin)  # ← Both factory and trait are clickable
    expect(admin.admin?).to be_truthy
  end
  
  it "creates post with multiple traits" do
    post = create(:post, :published, :featured)  # ← All traits are clickable
    expect(post).to be_published
    expect(post).to be_featured
  end
end

3. Navigate to Factories and Traits

Jump to Factory Definition:

  1. Hold Cmd (Mac) or Ctrl (Windows)
  2. Hover over a factory call (e.g., :user)
  3. Click the link to jump to the factory definition

Jump to Trait Definition:

  1. Hold Cmd (Mac) or Ctrl (Windows)
  2. Hover over a trait (e.g., :admin in create(:user, :admin))
  3. Click the link to jump directly to the trait definition within the factory

Supported Factory Methods

The extension detects these FactoryBot methods:

create(:user)                    # Basic factory creation
build(:user)                     # Build without saving
create_list(:user, 5)           # Create multiple records
build_list(:user, 3)            # Build multiple records
build_stubbed(:user)            # Build stubbed records
build_stubbed_list(:user, 2)    # Build multiple stubbed records

# With traits
create(:user, :admin)           # Factory with trait
build(:post, :published, :featured)  # Multiple traits

Configuration

Default Setup

The extension works out-of-box with standard Rails factory paths:

  • spec/factories/**/*.rb (default)

Custom Paths

Add to your VSCode settings (settings.json):

{
  "rails-factorybot-jump.factoryPaths": [
    "spec/factories/**/*.rb",
    "test/factories/**/*.rb",
    "lib/factories/**/*.rb"
  ]
}

Source: package.json#L55-L65

Verification

Test Factory Detection

  1. Open a factory file (e.g., spec/factories/users.rb):
FactoryBot.define do
  factory :user do
    name { "John Doe" }
    email { "[email protected]" }

    trait :admin do
      admin { true }
    end
    
    trait :verified do
      verified_at { Time.current }
    end
  end
  
  factory :post do
    title { "Sample Post" }
    content { "Lorem ipsum..." }
    
    trait :published do
      published_at { Time.current }
    end
    
    trait :featured do
      featured { true }
    end
  end
end
  1. Open a test file with factory calls
  2. Verify links appear when hovering over factory names and traits
  3. Test clicking on traits (e.g., :admin, :published) to jump to trait definitions

Troubleshooting

Links not appearing?

  • Ensure the extension is activated (check status bar)
  • Verify factory files exist in configured paths
  • Check that file language is set to Ruby

Wrong factory file opened?

  • Check for duplicate factory names
  • The extension prioritizes the first factory found

Configuration not working?

  • Restart VSCode after changing settings
  • Verify JSON syntax in settings.json

Next Steps