Bazel Central Registry

@rules_ruby//rails:rails_test_factory.bzl

Public definition for rails_test_factory.

Functions & Macros

rails_test_factory.new_system_test

Create a rails_system_test macro for a Rails application.

Parameters

`test_package`	Optional. The name of the package that contains the test helpers. For example, if the Rails app is rooted in the `foo` directory, the test package is typically `foo/test`. Default: `None`
`application_system_test_case`	Optional. The label for the Rails application's `application_system_test_case.rb`. Default: `None`
`default_includes`	Optional. A `list` of Ruby includes that should be part of the Ruby test invocation. Default: `None`
`default_size`	Optional. The default test size for the tests created with the resulting macro. Default: `"large"`
`tags`	Optional. A `list` of tags that are added to the test declaration. Default: `["no-sandbox"]`

rails_test_factory.new_test

Create a rails_test macro for a Rails application.

The resulting macro encapsulates the application-specific attributes for the
resulting test target.

Parameters

`test_package`	Optional. The name of the package that contains the test helpers. For example, if the Rails app is rooted in the `foo` directory, the test package is typically `foo/test`. Default: `None`
`test_helper`	The label for the Rails application's `test_helper.rb`. Default: `None`
`default_includes`	Optional. A `list` of Ruby includes that should be part of the Ruby test invocation. Default: `None`
`default_size`	Optional. The default test size for the tests created with the resulting macro. Default: `"small"`
`tags`	Optional. A `list` of tags that are added to the test declaration. Default: `[]`

@rules_ruby//ruby:defs.bzl

Public API for rules

Rules

rb_binary

Runs a Ruby binary.

Suppose you have the following Ruby gem, where rb_library() is used
in BUILD files to define the packages for the gem.

|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb

One of the files can be run as a Ruby script:

lib/gem/version.rb:

module GEM
  VERSION = '0.1.0'
end

puts "Version is: #{GEM::VERSION}" if __FILE__ == $PROGRAM_NAME

You can run this script by defining a target:

lib/gem/BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_binary", "rb_library")

rb_library(
    name = "version",
    srcs = ["version.rb"],
)

rb_binary(
    name = "print-version",
    args = ["lib/gem/version.rb"],
    deps = [":version"],
)

$ bazel run lib/gem:print-version
...
Version is: 0.1.0

You can also run general purpose Ruby scripts that rely on a Ruby interpreter in PATH:

lib/gem/add.rb:

#!/usr/bin/env ruby

a, b = *ARGV
puts Integer(a) + Integer(b)

lib/gem/BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_binary", "rb_library")

rb_library(
    name = "add",
    srcs = ["add.rb"],
)

rb_binary(
    name = "add-numbers",
    main = "add.rb",
    deps = [":add"],
)

$ bazel run lib/gem:add-numbers 1 2
...
3

You can also run a Ruby binary script available in Gemfile dependencies,
by passing bin argument with a path to a Bundler binary stub:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_binary")

package(default_visibility = ["//:__subpackages__"])

rb_binary(
    name = "rake",
    main = "@bundle//bin:rake",
    deps = [
        "//lib:gem",
        "@bundle",
    ],
)

$ bazel run :rake -- --version
...
rake, version 13.1.0

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`main`	`label`	Ruby script to run. It may also be a binary stub generated by Bundler. If omitted, it defaults to the Ruby interpreter. Use a built-in `args` attribute to pass extra arguments to the script. Default: `None`
`env`	`dictionary: String → String`	Environment variables to use during execution. Supports `$(location)` expansion for targets from `srcs`, `data` and `deps`. Default: `{}`
`env_inherit`	`list of strings`	List of environment variable names to be inherited by the test runner. Default: `[]`
`ruby`	`label`	Override Ruby toolchain to use when running the script. Default: `None`
`srcs`	`list of labels`	List of Ruby source files used to build the library. Default: `[]`
`data`	`list of labels`	List of runtime dependencies needed by a program that depends on this library. Default: `[]`
`deps`	`list of labels`	List of other Ruby libraries the target depends on. Default: `[]`

rb_bundle_install

Installs Bundler dependencies from cached gems.

You normally don't need to call this rule directly as it's an internal one
used by rb_bundle_fetch().

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*gemfile`	`label`	Gemfile to install dependencies from.
`*gemfile_lock`	`label`	Gemfile.lock to install dependencies from.
`*gems`	`list of labels`	List of gems in vendor/cache that are used to install dependencies from.
`jars`	`list of labels`	JAR dependencies for JRuby gems. Default: `[]`
`jars_path`	`string`	Path to the directory containing JAR dependencies (set as JARS_HOME). Default: `""`
`srcs`	`list of labels`	List of Ruby source files used to build the library. Default: `[]`
`env`	`dictionary: String → String`	Environment variables to use during installation. Default: `{}`
`ruby`	`label`	Override Ruby toolchain to use when installing the gem. Default: `None`

rb_gem

Exposes a Ruby gem file.

You normally don't need to call this rule directly as it's an internal one
used by rb_bundle_fetch().

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*gem`	`label`	Gem file.

rb_gem_build

Builds a Ruby gem.

Suppose you have the following Ruby gem, where rb_library() is used
in BUILD files to define the packages for the gem.

|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb

And a RubyGem specification is:

gem.gemspec:

root = File.expand_path(__dir__)
$LOAD_PATH.push(File.expand_path('lib', root))
require 'gem/version'

Gem::Specification.new do |s|
  s.name = 'example'
  s.version = GEM::VERSION

  s.authors = ['Foo Bar']
  s.email = ['foobar@gmail.com']
  s.homepage = 'http://rubygems.org'
  s.license = 'MIT'

  s.summary = 'Example'
  s.description = 'Example gem'
  s.files = ['Gemfile'] + Dir['lib/**/*']

  s.require_paths = ['lib']
  s.add_dependency 'rake', '~> 10'
  s.add_development_dependency 'rspec', '~> 3.0'
  s.add_development_dependency 'rubocop', '~> 1.10'
end

You can now package everything into a .gem file by defining a target:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_gem_build")

package(default_visibility = ["//:__subpackages__"])

rb_gem_build(
    name = "gem-build",
    gemspec = "gem.gemspec",
    deps = [
        "//lib:gem",
        "@bundle",
    ],
)

$ bazel build :gem-build
...
  Successfully built RubyGem
  Name: example
  Version: 0.1.0
  File: example-0.1.0.gem
...

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`srcs`	`list of labels`	List of Ruby source files used to build the library. Default: `[]`
`deps`	`list of labels`	List of other Ruby libraries the target depends on. Default: `[]`
`data`	`list of labels`	List of runtime dependencies needed by a program that depends on this library. Default: `[]`
`bundle_env`	`dictionary: String → String`	List of bundle environment variables to set when building the library. Default: `{}`
`ruby`	`label`	Override Ruby toolchain to use when running the script. Default: `None`
`*gemspec`	`label`	Gemspec file to use for gem building.

rb_gem_install

Installs a built Ruby gem.

Suppose you have the following Ruby gem, where rb_library() is used
in BUILD files to define the packages for the gem and rb_gem_build() is used
to build a Ruby gem package from the sources.

|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb

You can now install the built .gem file by defining a target:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_gem_build", "rb_gem_install")

package(default_visibility = ["//:__subpackages__"])

rb_gem_build(
    name = "gem-build",
    gemspec = "gem.gemspec",
    deps = ["//lib:gem"],
)

rb_gem_install(
    name = "gem-install",
    gem = ":gem-build",
)

$ bazel build :gem-install
...
Successfully installed example-0.1.0
1 gem installed
...

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*gem`	`label`	Gem file to install.
`ruby`	`label`	Override Ruby toolchain to use when installing the gem. Default: `None`

rb_gem_push

Pushes a built Ruby gem.

Suppose you have the following Ruby gem, where rb_library() is used
in BUILD files to define the packages for the gem and rb_gem_build() is used
to build a Ruby gem package from the sources.

|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb

You can now release the built .gem file to RubyGems by defining a target:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_gem_build", "rb_gem_push")

package(default_visibility = ["//:__subpackages__"])

rb_gem_build(
    name = "gem-build",
    gemspec = "gem.gemspec",
    deps = ["//lib:gem"],
)

rb_gem_push(
    name = "gem-release",
    gem = ":gem-build",
)

$ bazel run :gem-release
...
Pushing gem to https://rubygems.org...
Successfully registered gem: example (0.1.0)

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`srcs`	`list of labels`	List of Ruby source files used to build the library. Default: `[]`
`deps`	`list of labels`	List of other Ruby libraries the target depends on. Default: `[]`
`data`	`list of labels`	List of runtime dependencies needed by a program that depends on this library. Default: `[]`
`bundle_env`	`dictionary: String → String`	List of bundle environment variables to set when building the library. Default: `{}`
`*gem`	`label`	Gem file to push to RubyGems. You would usually use an output of `rb_gem_build()` target here.
`env`	`dictionary: String → String`	Environment variables to use during execution. Supports `$(location)` expansion for targets from `srcs`, `data` and `deps`. Default: `{}`
`env_inherit`	`list of strings`	List of environment variable names to be inherited by the test runner. Default: `[]`
`ruby`	`label`	Override Ruby toolchain to use when running the script. Default: `None`

rb_library

Defines a Ruby library.

Suppose you have the following Ruby gem:

|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb

You can define packages for the gem source files:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_library")

package(default_visibility = ["//:__subpackages__"])

rb_library(
    name = "gem",
    deps = ["//lib:gem"],
)

lib/BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_library")

package(default_visibility = ["//:__subpackages__"])

rb_library(
    name = "gem",
    srcs = ["gem.rb"],
    deps = [
        "//lib/gem:add",
        "//lib/gem:subtract",
        "//lib/gem:version",
    ],
)

lib/gem/BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_library")

package(default_visibility = ["//:__subpackages__"])

rb_library(
    name = "add",
    srcs = ["add.rb"],
)

rb_library(
    name = "subtract",
    srcs = ["subtract.rb"],
)

rb_library(
    name = "version",
    srcs = ["version.rb"],
)

Once the packages are defined, you can use them in other targets
such as rb_gem_build() to build a Ruby gem. See examples of
using other rules.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`srcs`	`list of labels`	List of Ruby source files used to build the library. Default: `[]`
`deps`	`list of labels`	List of other Ruby libraries the target depends on. Default: `[]`
`data`	`list of labels`	List of runtime dependencies needed by a program that depends on this library. Default: `[]`
`bundle_env`	`dictionary: String → String`	List of bundle environment variables to set when building the library. Default: `{}`

rb_test

Runs a Ruby test.

Suppose you have the following Ruby gem, where rb_library() is used
in BUILD files to define the packages for the gem.

|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
|-- lib
|   |-- BUILD
|   |-- gem
|   |   |-- BUILD
|   |   |-- add.rb
|   |   |-- subtract.rb
|   |   `-- version.rb
|   `-- gem.rb
`-- spec
    |-- BUILD
    |-- add_spec.rb
    |-- spec_helper.rb
    `-- subtract_spec.rb

You can run all tests inside spec/ by defining individual targets:

spec/BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_library", "rb_test")

rb_library(
    name = "spec_helper",
    srcs = ["spec_helper.rb"],
)

rb_test(
    name = "add",
    srcs = ["add_spec.rb"],
    args = ["spec/add_spec.rb"],
    main = "@bundle//bin:rspec",
    deps = [
        ":spec_helper",
        "@bundle",
    ],
)

rb_test(
    name = "subtract",
    srcs = ["subtract_spec.rb"],
    args = ["spec/subtract_spec.rb"],
    main = "@bundle//bin:rspec",
    deps = [
        ":spec_helper",
        "@bundle",
    ],
)

$ bazel test spec/...
...
//spec:add                                                               PASSED in 0.4s
//spec:subtract                                                          PASSED in 0.4s

Executed 2 out of 2 tests: 2 tests pass.

Since rb_test() is a wrapper around rb_binary(), you can also use it to run
a Ruby binary script available in Gemfile dependencies, by passing main
argument with a path to a Bundler binary stub.

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_test")

package(default_visibility = ["//:__subpackages__"])

rb_test(
    name = "rubocop",
    args = ["lib/"],
    main = "@bundle//bin:rubocop",
    tags = ["no-sandbox"],
    deps = [
        "//lib:gem",
        "@bundle",
    ],
)

$ bazel test :rubocop
...
//:rubocop                                                               PASSED in 0.8s

Executed 1 out of 1 test: 1 test passes.

Note that you can also run every test target passing extra arguments to
the Ruby script. For example, you can re-use :rubocop target to perform autocorrect:

$ bazel run :rubocop -- --autocorrect-all
...
Inspecting 11 files
.C.........

Offenses:

gem.gemspec:1:1: C: [Corrected] Style/FrozenStringLiteralComment: Missing frozen string literal comment.
root = File.expand_path(__dir__)
^
gem.gemspec:2:1: C: [Corrected] Layout/EmptyLineAfterMagicComment: Add an empty line after magic comments.
root = File.expand_path(__dir__)
^

11 files inspected, 2 offenses detected, 2 offenses corrected

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`main`	`label`	Ruby script to run. It may also be a binary stub generated by Bundler. If omitted, it defaults to the Ruby interpreter. Use a built-in `args` attribute to pass extra arguments to the script. Default: `None`
`env`	`dictionary: String → String`	Environment variables to use during execution. Supports `$(location)` expansion for targets from `srcs`, `data` and `deps`. Default: `{}`
`env_inherit`	`list of strings`	List of environment variable names to be inherited by the test runner. Default: `[]`
`ruby`	`label`	Override Ruby toolchain to use when running the script. Default: `None`
`srcs`	`list of labels`	List of Ruby source files used to build the library. Default: `[]`
`data`	`list of labels`	List of runtime dependencies needed by a program that depends on this library. Default: `[]`
`deps`	`list of labels`	List of other Ruby libraries the target depends on. Default: `[]`

@rules_ruby//ruby:deps.bzl

Public API for repository rules

Functions & Macros

rb_bundle

Wraps rb_bundle_rule() providing default toolchain name.

Parameters

`toolchain`	default Ruby toolchain BUILD Default: `"@ruby//:BUILD"`
`kwargs`	underlying attrs passed to rb_bundle_rule()

rb_register_toolchains

(For MRI on Linux and macOS) Installed using ruby-build.
(For MRI on Windows) Installed using RubyInstaller.
(For JRuby on any OS) Downloaded and installed directly from official website.
(For TruffleRuby on Linux and macOS) Installed using ruby-build.
(With portable_ruby) Portable Ruby downloaded from jdx/ruby.
(For "system") Ruby found on the PATH is used. Please note that builds are not hermetic in this case.

WORKSPACE:

load("@rules_ruby//ruby:deps.bzl", "rb_register_toolchains")

rb_register_toolchains(
    version = "3.0.6"
)

Once registered, you can use the toolchain directly as it provides all the binaries:

$ bazel run @ruby -- -e "puts RUBY_VERSION"
$ bazel run @ruby//:bundle -- update
$ bazel run @ruby//:gem -- install rails

You can also use Ruby engine targets to select() depending on installed Ruby interpreter:

BUILD:

rb_library(
    name = "my_lib",
    srcs = ["my_lib.rb"],
    deps = select({
        "@ruby//engine:jruby": [":my_jruby_lib"],
        "@ruby//engine:truffleruby": ["//:my_truffleruby_lib"],
        "@ruby//engine:ruby": ["//:my__lib"],
        "//conditions:default": [],
    }),
)

Parameters

`name`	base name of resulting repositories, by default "ruby" Default: `"ruby"`
`version`	a semver version of MRI, or a string like [interpreter type]-[version], or "system" Default: `None`
`version_file`	.ruby-version or .tool-versions file to read version from Default: `None`
`msys2_packages`	extra MSYS2 packages to install Default: `["libyaml"]`
`portable_ruby`	when True, downloads portable Ruby from jdx/ruby instead of compiling via ruby-build. Has no effect on JRuby, TruffleRuby, or Windows. Default: `False`
`portable_ruby_checksums`	platform checksums for portable Ruby downloads, overriding built-in checksums. Keys: linux-x86_64, linux-arm64, macos-arm64, macos-x86_64. Default: `{}`
`register`	whether to register the resulting toolchains, should be False under bzlmod Default: `True`
`kwargs`	additional parameters to the downloader for this interpreter type

Repository Rules

rb_bundle_fetch

Fetches Bundler dependencies to be automatically installed by other targets.

Currently doesn't support installing gems from Git repositories,
see https://github.com/bazel-contrib/rules_ruby/issues/62.

WORKSPACE:

load("@rules_ruby//ruby:deps.bzl", "rb_bundle_fetch")

rb_bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
    srcs = [
        "//:gem.gemspec",
        "//:lib/gem/version.rb",
    ]
)

Checksums for gems in Gemfile.lock are printed by the ruleset during the build.
It's recommended to add them to gem_checksums attribute.

WORKSPACE:

rb_bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
    gem_checksums = {
        "ast-2.4.2": "1e280232e6a33754cde542bc5ef85520b74db2aac73ec14acef453784447cc12",
        "concurrent-ruby-1.2.2": "3879119b8b75e3b62616acc256c64a134d0b0a7a9a3fcba5a233025bcde22c4f",
    },
)

All the installed gems can be accessed using @bundle target and additionally
gems binary files can also be used via BUILD rules or directly with bazel run:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_test")

package(default_visibility = ["//:__subpackages__"])

rb_test(
    name = "rubocop",
    main = "@bundle//bin:rubocop",
    deps = ["@bundle"],
)

Attribute	Type	Description
`*name`	`name`	A unique name for this repository.
`repo_mapping`	`dictionary: String → String`	In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). This attribute is not supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).
`*gemfile`	`label`	Gemfile to install dependencies from.
`*gemfile_lock`	`label`	Gemfile.lock to install dependencies from.
`srcs`	`list of labels`	List of Ruby source files necessary during installation. Default: `[]`
`env`	`dictionary: String → String`	Environment variables to use during installation. Default: `{}`
`bundler_remote`	`string`	Remote to fetch the bundler gem from. Default: `"https://rubygems.org/"`
`bundler_checksums`	`dictionary: String → String`	Custom map from Bundler version to its SHA-256 checksum. Default: `{}`
`gem_checksums`	`dictionary: String → String`	SHA-256 checksums for remote gems. Keys are gem names (e.g. foobar-1.2.3), values are SHA-256 checksums. Default: `{}`
`jar_checksums`	`dictionary: String → String`	SHA-256 checksums for JAR dependencies. Keys are Maven coordinates (e.g. org.yaml:snakeyaml:1.33), values are SHA-256 checksums. Default: `{}`
`ruby`	`label`	Override Ruby toolchain to use for installation. Default: `None`
`auth_patterns`	`dictionary: String → String`	A list of patterns to match against urls for which the auth object should be used. Default: `{}`
`netrc`	`string`	Path to .netrc file to read credentials from Default: `""`

rb_bundle_rule

(Deprecated) Use rb_bundle_fetch() instead.

Installs Bundler dependencies and registers an external repository
that can be used by other targets.

WORKSPACE:

load("@rules_ruby//ruby:deps.bzl", "rb_bundle")

rb_bundle(
    name = "bundle",
    gemfile = "//:Gemfile",
    srcs = [
        "//:gem.gemspec",
        "//:lib/gem/version.rb",
    ]
)

All the installed gems can be accessed using @bundle target and additionally
gems binary files can also be used:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_binary")

package(default_visibility = ["//:__subpackages__"])

rb_binary(
    name = "rubocop",
    main = "@bundle//:bin/rubocop",
    deps = ["@bundle"],
)

Attribute	Type	Description
`*name`	`name`	A unique name for this repository.
`repo_mapping`	`dictionary: String → String`	In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). This attribute is not supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).
`srcs`	`list of labels`	List of Ruby source files used to build the library. Default: `[]`
`*toolchain`	`label`
`gemfile`	`label`	Gemfile to install dependencies from. Default: `None`
`env`	`dictionary: String → String`	Environment variables to use during installation. Default: `{}`