samvera-labs / hyrax-spec

Shared tests and smoke tests for the Hyrax Samvera engine.

Hyrax::Spec

Shared examples and smoke tests for Hyrax applications. See the documentation for more information.

RSpec Matchers

Hyrax::Spec::Matchers includes a variety of custom matchers for use with RSpec. These matchers can be included in your suite in batch by adding require 'hyrax/spec/matchers' to your test helper (usually spec/rails_helper.rb), or individually requiring them (as in require 'hyrax/spec/matchers/have_form_field').

Note: documentation on matchers remains somewhat thin. The best current reference is their use in mahonia, an ETD repository.

FactoryBot Build Strategies for Hyrax

If your test suite uses FactoryBot (formerly FactoryGirl) to create test objects, Hyrax::Spec provides useful custom build strategies that may simplify the setup phase of your tests. To register the build stratgies add the following to your test helper (usually spec/rails_helper.rb):

# spec/rails_helper.rb

require 'hyrax/spec/factory_bot/build_strategies'

ActorCreate

The ActorCreate strategy builds an object and passes it to the Hyrax Actor Stack to be processed. In a normal RSpec Rails environment, this will enqueue (but not perform) several background jobs (charactarization, derivatives, etc...). The specific actor middleware called is Hyrax::CurationConcern.actor.

This strategy is registered by default as actor_create. You can use it with an existing factory, which must define user as a transient attribute.

# factories/my_works.rb
FactoryBot.define do
  factory(:my_work) do
    title ['Comet in Moominland']

    transient do
      user { FactoryBot.create(:user) }
    end
  end
end

# my_work_spec.rb
RSpec.describe MyWork do
  subject(:my_work) { FactoryBot.actor_create(:my_work) }

  it { is_expected.to have_attributes(date_uploaded: an_instance_of(DateTime)) }
end

Contributing

If you're working on a PR for this project, create a feature branch off of main.

This repository follows the Samvera Community Code of Conduct and language recommendations. Please do not create a branch called master for this repository or as part of your pull request; the branch will either need to be removed or renamed before it can be considered for inclusion in the code base and history of this repository.

License

Hyrax::Spec is available under the Apache 2.0 license.

hyrax-spec's Issues

Sketch & document initial tags

We added a :slow tag to exclude from default rspec runs at project initialization. Other tags will likely be useful to filter or focus on certain types of tests. It would be useful to have some strategy at the outset, so things can stay relatively organized.

Setup Hyrax builds

We currently have a build matrix that handles the Rails versions also tested by Hyrax, but we don't have an actual base Hyrax engine to test against.

We need to get engine cart (or similar) up, and run the tests in this suite against it as the test suite for this codebase. i.e. we should run the tests in lib/hyrax/spec/**/* against a base app when bundle exec rake is run. Ensure the correct versions of Rails are installed in the build matrix.

Decide on testing framework

We've included rspec for unit tests, which seems natural. We will want to include shared examples for various hyrax mixins and related behavior sets here, as a development aid.

But this should also include slow running feature, integration, and contract tests not included in Hyrax. What frameworks are best to use for these? How can we make those tests maximally manageable?

This ticket is to have a discussion about the above. Any decisions that are made at that point should be documented in the README.md, or other appropriate places.

Decide on a versioning strategy

Which Hyrax versions does this test? How do versions of hyrax-spec align with versions of hyrax?