{"id":12167898,"url":"https://github.com/Darhazer/active_record_change_matchers","last_synced_at":"2025-10-19T20:30:22.072Z","repository":{"id":247054452,"uuid":"823853933","full_name":"Darhazer/active_record_change_matchers","owner":"Darhazer","description":"Custom RSpec matchers for ActiveRecord record creation.","archived":false,"fork":false,"pushed_at":"2025-05-20T13:22:39.000Z","size":69,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-30T22:35:43.679Z","etag":null,"topics":["active-record","rspec","rspec-custom-matchers","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Darhazer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-03T21:32:04.000Z","updated_at":"2025-05-20T13:22:43.000Z","dependencies_parsed_at":"2024-07-06T10:33:15.230Z","dependency_job_id":"cb454802-5efe-4024-b140-6a019c0ce519","html_url":"https://github.com/Darhazer/active_record_change_matchers","commit_stats":{"total_commits":63,"total_committers":6,"mean_commits":10.5,"dds":0.6190476190476191,"last_synced_commit":"2c03d692cbcaa7a99a88ddb4fbfbbc391f81733f"},"previous_names":["darhazer/active_record_change_matchers"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Darhazer/active_record_change_matchers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Darhazer%2Factive_record_change_matchers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Darhazer%2Factive_record_change_matchers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Darhazer%2Factive_record_change_matchers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Darhazer%2Factive_record_change_matchers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Darhazer","download_url":"https://codeload.github.com/Darhazer/active_record_change_matchers/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Darhazer%2Factive_record_change_matchers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279902617,"owners_count":26241837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-19T02:00:07.647Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["active-record","rspec","rspec-custom-matchers","ruby"],"created_at":"2024-07-06T10:02:10.150Z","updated_at":"2025-10-19T20:30:21.822Z","avatar_url":"https://github.com/Darhazer.png","language":"Ruby","funding_links":[],"categories":["Matchers"],"sub_categories":[],"readme":"# active_record_change_matchers\n\nCustom RSpec matchers for ActiveRecord record creation.\nThis is a hard-fork of [active_record_block_matchers](https://github.com/nwallace/active_record_block_matchers). See [the changelog](CHANGELOG.md) for changes since the original gem was written.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'active_record_change_matchers'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install active_record_change_matchers\n\n## Quick Examples\n\n```ruby\nexpect {\n  post :create, user: { username: \"bob\", password: \"BlueSteel45\" }\n}.to create_a(User)\n  .with_attributes(username: \"bob\")\n  .which {|bob| expect(AuthLibrary.authenticate(\"bob\", \"BlueSteel45\")).to eq bob }\n\nexpect {\n  post :create, user: { username: \"bob\", password: \"BlueSteel45\" }\n}.to create(User =\u003e 1, Profile =\u003e 1)\n  .with_attributes(\n    User =\u003e [{username: \"bob\"}],\n    Profile =\u003e [{avatar_url: Avatar.default_avatar_url}],\n  ).which { |new_records_hash|\n    new_user = new_records_hash[User].first\n    new_profile = new_records_hash[Profile].first\n    expect(new_user.profile).to eq new_profile\n  }\n```\n\n## Detailed Examples\n\n#### `create_a`\n\naliases: `create_an`, `create_a_new`\n\nExample:\n\n```ruby\nexpect { User.create! }.to create_a(User)\n```\n\nThis can be very useful for controller tests:\n\n```ruby\nexpect { post :create, user: user_params }.to create_a(User)\n```\n\nYou can chain `.with_attributes` as well to define a list of values you expect the new object to have.  This works with both database attributes and computed values.\n\n```ruby\nexpect { User.create!(username: \"bob\") }\n  .to create_a(User)\n  .with_attributes(username: \"bob\")\n```\n\nThis is a great way to test ActiveReocrd hooks on your model.  For example, if your User model downcases all usernames before saving them to the database, you can test it like this:\n\n```ruby\nexpect { User.create!(username: \"BOB\") }\n  .to create_a(User)\n  .with_attributes(username: \"bob\")\n```\n\nYou can even use RSpec's [composable matchers][^1]:\n\n```ruby\nexpect { User.create!(username: \"bob\") }\n  .to create_a(User)\n  .with_attributes(username: a_string_starting_with(\"b\"))\n```\n\nIf you need to make assertions about things other than attribute equality, you can also chain `.which_is_expected_to` with a (composable) matcher:\n\n```ruby\nexpect { User.create!(username: \"BOB\", password: \"BlueSteel45\") }\n  .to create_a(User)\n  .which_is_expected_to(\n    have_attributes(encrypted_password: be_present)\n    .and(eq(AuthLibrary.authenticate(\"bob\", \"BlueSteel45\")))\n  )\n```\n\nIf that's doesn't provide enough flexibility, you can also chain `.which` with a block, and your block will receive the newly created record:\n\n```ruby\nexpect { User.create!(username: \"BOB\", password: \"BlueSteel45\") }\n  .to create_a(User)\n  .which { |user|\n    expect(user.encrypted_password).to be_present\n    expect(AuthLibrary.authenticate(\"bob\", \"BlueSteel45\")).to eq user\n  }\n```\n\n\u003e [!WARNING]\n\u003e Be careful about your block syntax when chaining `.which` in your tests. If you write the above example with a `do...end`, the example will parse like this: `expect {...}.to(create_a(User).which) do |user| ... end`, so your block will not execute, and it may appear that your test is passing, when it is not.\n\n#### `create`\n\naliases: `create_records`\n\nExample:\n\n```ruby\nexpect { User.create!; User.create!; Profile.create! }\n  .to create(User =\u003e 2, Profile =\u003e 1)\n```\n\nJust like the other matcher, you can chain `with_attributes` and `which` to assert about the particulars of the records:\n\n```ruby\nexpect { UserService.sign_up!(username: \"bob\", password: \"BlueSteel45\") }\n  .to create(User =\u003e 1, Profile =\u003e 1)\n  .with_attributes(\n    User =\u003e [{username: \"bob\"}],\n    Profile =\u003e [{avatar_url: Avatar.default_avatar_url}]\n  ).which { |records|\n    # records is a hash with model classes for keys and the new records for values\n    new_user = records[User].first\n    new_profile = records[Profile].first\n    expect(AuthLibrary.authenticate(\"bob\", \"BlueSteel45\")).to eq new_user\n    expect(new_user.profile).to eq new_profile\n  }\n```\n\nAs noted, the `which` block yields a hash containing the new records whose counts were specified.\n\nOrder doesn't matter for the attributes specified in `with_attributes`, but you must provide an attribute hash for every record that was created. This means, if you expect the block to create, say 2 User records, you must provide an attributes hash for each new User record:\n\n```ruby\n# This is correct:\nexpect { User.create!(username: \"bob\"); User.create!(username: \"rhonda\") }\n  .to create(User =\u003e 2)\n  .with_attributes(\n    User =\u003e [{username: \"rhonda\"}, {username: \"bob\"}]\n  )\n\n# This will raise an error:\nexpect { User.create!(username: \"bob\"); User.create!(username: \"rhonda\") }\n  .to create(User =\u003e 2)\n  .with_attributes(\n    User =\u003e [{username: \"rhonda\"}]\n  )\n\n# But this is totally fine if you really need a workaround:\n# Just put the empty hashes last\nexpect { User.create!(username: \"bob\"); User.create!(username: \"rhonda\") }\n  .to create(User =\u003e 2)\n  .with_attributes(\n    User =\u003e [{username: \"rhonda\"}, {}]\n  )\n```\n\n## Record Retrieval Strategies\n\nThere are currently two retrieval strategies implemented: `:id` and `:timestamp`. `:id` is the default, but this can be configured via the `default_strategy` configuration variable (more details [below](#configuration)).\n\nThe ID and Timestamp Strategies work similarly. The ID Strategy queries the appropriate table(s) to find the highest ID value(s) before the block, then finds new records by looking for records with an ID that higher than that. The Timestamp Strategy uses `Time.current` to record the time before the block. Then it finds new records by looking for records that have a timestamp later than that.\n\nThe ID Strategy is the default because it doesn't rely on time values that may be imprecise or mocked out. The Timestamp Strategy is useful if your tables don't have autoincrementing integer primary keys.\n\n## Configuration\n\nYou can configure the column names used by the ID or Timestamp Strategies. Put code like this in your `spec_helper.rb` or similar file:\n\n```ruby\nActiveRecordChangeMatchers::Config.configure do |config|\n\n  # default value is \"id\"\n  config.id_column_name = \"primary_key\"\n\n  # default value is \"created_at\"\n  config.created_at_column_name = \"created_timestamp\"\n\n  # default value is :id\n  # must be one of [:id, :timestamp]\n  config.default_strategy = :timestamp\nend\n```\n\nYou can also override the default strategy for individual assertions if needed:\n\n```ruby\nexpect { Person.create! }.to create_a(Person, strategy: :id)\n```\n\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n## Contributing\n\n1. Fork it ( https://github.com/[my-github-username]/active_record_change_matchers/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n\n[^1]: https://rspec.info/features/3-13/rspec-expectations/composing-matchers/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDarhazer%2Factive_record_change_matchers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDarhazer%2Factive_record_change_matchers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDarhazer%2Factive_record_change_matchers/lists"}