DOCSEARCHbyAlgolia
Submit Docs

Magic Test Documentation

repository·main·Indexed 19 days ago

https://github.com/bullet-train-co/magic_test

A tool for Rails developers to write system tests interactively by combining a debugger session with a browser-based recorder. It allows users to write Capybara code by typing commands in a console or clicking through the application, supporting both MiniTest and RSpec. Key features include the `bin/magic` CLI, the `magic_test` method for initiating sessions, and the `flush` and `ok` commands to persist recorded actions and debugger commands directly to test files.

Tokens
2.7K
Snippets
13
Records
17
Agent score
66%

What's inside Magic Test

  1. How to use Magic Test for interactive development

    main

    Magic Test provides a three-window developer experience:

    1. A debugger: Where you can type Capybara commands manually.
    2. A browser: Where you can click through the app to record actions.
    3. An editor: Where you watch the generated test code appear.

    Using in existing tests

    To start an interactive session in any existing or new system test, simply call the magic_test method at the point where you want the interaction to begin.

    # Inside a system test
# ... setup code ...
magic_test
# Interaction starts here

  2. Install Magic Test in a Rails application

    main

    To install Magic Test, add the gem to your Gemfile in the :test group, install the dependencies, and run the installation generator.

    Important Manual Step: If your application views contain explicit <head></head> tags, you must manually place the following snippet before the closing </head> tag to ensure Magic Test can function:

    <%= render 'magic_test/support' if Rails.env.test? %>
    gem 'magic_test', group: :test
    bundle install
rails g magic_test:install
bundle binstubs magic_test

  3. Record actions and generate assertions in the browser

    main

    You can record test steps by interacting with the application in the browser window provided by Magic Test.

    Recording Actions

    Click buttons, links, and fill in forms as a normal user. These actions are tracked for later flushing.

    Generating Assertions

    To assert that specific text exists on the page, use one of these two methods:

    1. Keyboard Shortcut: Highlight the text and press Control + Shift + A. Confirm the action in the dialog.
    2. Mouse: Highlight the text and right-click.

    Saving to the Test File

    Actions and assertions are not automatically written to the file. To save your recorded work, go to the terminal/debugger window and type:

    flush

  4. Write tests manually in the debugger console

    main

    While the test is running in Magic Test mode, you can use the debugger to issue Capybara commands directly.

    • Save a command: Type the Capybara command, then type ok and press Enter to append the last line or block to the test file.
    • Finish the session: Press Control + D to stop the debugger and finish running the test.
    • Resume work: You can re-run the test command to execute up to your last breakpoint and re-enter the session to continue writing.

  5. Magic Test integration with test frameworks

    main

    When MAGIC_TEST is enabled, the engine automatically injects MagicTest::Support into the following test types:

    • Rails System Tests: Includes MagicTest::Support into ActionDispatch::SystemTestCase.
    • Rails Integration Tests: Includes MagicTest::Support into ActionDispatch::IntegrationTest.
    • RSpec System Tests: Configures RSpec to include MagicTest::Support for all tests with type: :system.

  6. Enable Magic Test via environment variable

    main

    Magic Test is integrated into your Rails application via a Rails Engine. To activate the Magic Test features (such as including MagicTest::Support into your test suites), you must set the MAGIC_TEST environment variable to a present value (e.g., export MAGIC_TEST=true) when running your test environment or server.

    export MAGIC_TEST=true
# then run your tests
bin/rails test

  7. Run Magic Test system tests

    main

    Once installed, you can run your system tests in interactive Magic Test mode using one of two methods:

    Method 1: Using the Rails test command

    Set the MAGIC_TEST environment variable to 1 when running your tests:

    MAGIC_TEST=1 rails test test/system/basics_test.rb

    Method 2: Using Magic Test binstubs

    Generate a binstub for the gem and use the bin/magic executable:

    bundle binstubs magic_test
bin/magic test test/system/basics_test.rb

    Behavioral Note: When MAGIC_TEST=1 is set, the configuration in test/application_system_test_case.rb automatically switches from headless browsers to headed browsers (e.g., :chrome instead of :headless_chrome) and adjusts the screen size to [800, 1400] to facilitate interaction.

    MAGIC_TEST=1 rails test test/system/basics_test.rb

  8. Install Magic Test into a Rails application

    main

    Magic Test is installed into a Rails application using a Rails generator. The installation process performs the following actions:

    1. Adds gem "magic_test" to the :test group in your Gemfile.
    2. Generates a sample system test at test/system/basics_test.rb.
    3. Updates test/application_system_test_case.rb to configure browser behavior based on the MAGIC_TEST environment variable.
    4. Injects <%= render 'magic_test/support' if Rails.env.test? %> before the </head> tag in all application layout templates (excluding mailers).

    Note: If your application uses custom partials for the <head> section (e.g., views/shared/_head.html.erb), you must manually paste the render snippet <%= render 'magic_test/support' if Rails.env.test? %> inside those tags to ensure Magic Test works correctly.

    bundle exec rails generate magic_test:install

  9. Troubleshoot Magic Test browser requirements

    main

    If you encounter errors when calling empty_cache (which is called internally by magic_test and flush), it is likely because the driver does not support sessionStorage or is running in a mode that prevents interaction.

    Error Message: "You need to configure this test (or your test suite) to run in a real browser (Chrome, Firefox, etc.) in order for Magic Test to work. It also needs to run in non-headless mode if ENV['MAGIC_TEST'].present?"

    Solution: Ensure your Capybara driver is configured for a real browser and that headless mode is disabled when testing with Magic Test.

  10. Run Magic Test using the CLI

    main

    Magic Test provides a binstub to run tests with the MAGIC_TEST=1 environment variable automatically set. This enables the interactive debugger and visible browser mode.

    Use the following commands depending on your testing framework:

    • MiniTest: bin/magic test path/to/test.rb
    • RSpec: bin/magic spec path/to/spec.rb

    Under the hood, these commands execute: MAGIC_TEST=1 rails test ... or MAGIC_TEST=1 rspec ....

    # For MiniTest
bin/magic test test/system/basics_test.rb

# For RSpec
bin/magic spec spec/system/basics_spec.rb

  11. Generate assertions for selected text

    main

    The assert_selected_exists method allows you to highlight text in the browser and automatically generate a Capybara assertion in your test file. It retrieves the currently selected text via the browser's window.selectedText() function and writes an assert(page.has_content?('...')) line into your test file at the current line position.

    def test_content_check
  visit some_path
  # Select text in the browser manually
  assert_selected_exists
end

  12. Write debugger commands to the test file using ok

    main

    The ok method takes the last command(s) entered in the Pry debugger console and writes them directly into your test file. This is useful for 'recording' manual debugging steps or complex commands that you want to persist as part of the test suite.

    def test_with_manual_steps
  magic_test
  # In Pry console:
  # [1] pry> visit '/path'
  # [2] pry> ok
  # 'visit "/path"' is now written to the test file.
end