Sufia Development Guide

The Sufia Development Guide is for people who want to modify Sufia itself. See the Sufia Management Guide for guidance on how to configure and set up a Sufia-based application.

• Run the test suite
  • Prerequisites
  • Generate test app
  • Run the wrappers
  • Run tests
  • Troubleshooting / Testing FAQ
• Work with test app in the browser
  • Cleaning up
• Change validation behavior
• Regenerating the README TOC

Run the test suite

Prerequisites

• Make sure all basic prerequisites are running.
• Additional prerequisite for tests: PhantomJS.

Generate test app

NOTE: Run this only once.

cd <sufia directory>
rake engine_cart:generate

This generates sufia/.internal_test_app directory. The tests will run against this test app.

Run the wrappers

Note: DO NOT USE FOR PRODUCTION

Start Solr:

#  from <sufia root>/.internal_test_app in a separate terminal window 
#  if the file config/solr_wrapper_test.yml exists (created below in step two or by ActiveFedora generators)
solr_wrapper --config config/solr_wrapper_test.yml
# - or - from sufia root in a separate terminal window
solr_wrapper -d solr/config/ -n hydra-test -p 8985

Start Fedora:

#  from <sufia root>/.internal_test_app in a separate terminal window 
#  if the file config/fcrepo_wrapper_test.yml exists (created below in step two or by ActiveFedora generators)
fcrepo_wrapper --config config/fcrepo_wrapper_test.yml
# - or - from sufia root in a separate terminal window
fcrepo_wrapper -p 8986 --no-jms

Run tests

Run entire suite:

cd <sufia directory>
rake spec

Run a single spec:

rspec path/to/filel_spec.rb

Run Rubocop style checker:

rubocop

or, to have rubocop autofix errors (only if you git commit first!):

rubocop -a

Troubleshooting / Testing FAQ

• The generated test app isn't doing what I expected after making (and/or pulling) changes to Sufia. What can I do? Generally, engine cart will pick up changes to Sufia. If not, try the following to regenerate the test app:

  cd <sufia directory>
  rm -rf .internal_test_app Gemfile.lock
  bundle install
  rake engine_cart:generate

• Where is rake jetty? It was retired. Solr and Fedora now run individually; see Run the wrappers.

• Test that Solr is running. In a web browser check localhost:8985. You should see an instance of Solr with a Solr core name of hydra-test

• Test that Fedora is running. In a web browser check localhost:8986. You should see the Fedora splash page.

• Those ports look different. They are! Now that we use solr_wrapper and fcrepo_wrapper instead of hydra-jetty, which bundled test and dev environments together and was occasionally problematic, test and dev instances of Solr and Fedora now run on separate ports. If you want to run the test suite, use the ports above (8985 for Solr and 8986 for Fedora). If you want to check out Sufia in your browser, use port 8983 for Solr and port 8984 for Fedora as stated in Creating a Sufia-based app: Solr and Fedora.

• How do I run the code coverage report? Just let travis handle this when you submit your PR. but if you really want to run it locally:

  COVERAGE=true rspec
  

• You can run everything (including fedora, solr wrappers) using the default task:

  rake
  

Work with test app in the browser

You may want to see the test application in your browser to verify that your changes look correct. This section assumes that you have generated the test app via rake engine_cart:generate.

1. Verify that ActiveFedora has installed the development templates by looking for .internal_test_app/config/solr_wrapper_test.yml. (Note: As of the latest draft of this document, ActiveFedora has not been released with this change. If the file exists skip to step 3.)

2. Copy the templates from ActiveFedora

   Unfortunately this will need to be done each time you regenerate the test application. This step is a bit hacky and should go away once the latest ActiveFedora has been released with this commit: c8309ae.

3. Get the following dev environment-related files from ActiveFedora and put them in .internal_test_app/: * .fcrepo_wrapper * .solr_wrapper

   Note: These two files are dot files and are not visible unless you add the -a flag to ls.

4. Get the following test environment-related files from ActiveFedora and put them in .internal_test_app/config:

   • fcrepo_wrapper_test.yml
   • solr_wrapper_test.yml

5. Run SolrWrapper in development mode. SolrWrapper picks up configuration from the .solr_wrapper file. By default ActiveFedora installs a configuration file (to .internal_test_app/.solr_wrapper) that starts Solr on port 8983.

6. Open a terminal

7. cd <sufia directory>\.internal_test_app

8. solr_wrapper

9. Run FcrepoWrapper in development mode. FcrepoWrapper picks up configuration from the .fcrepo_wrapper file. By default ActiveFedora installs a configuration file (to .internal_test_app/.fcrepo_wrapper) that starts Fedora on port 8984.

10. Open a terminal

11. cd <sufia directory>\.internal_test_app

12. fcrepo_wrapper

13. Run the Rails server in development mode

14. Open a terminal

15. cd <sufia directory>\.internal_test_app

16. rails s

17. View the app by opening localhost:3000 in a web browser.

Cleaning up

1. To stop the servers, press CTRL-C in the terminal windows
2. To clean out the data in Solr & Fedora
3. cd <sufia directory>\.internal_test_app
4. fcrepo_wrapper clean
5. solr_wrapper clean

Change validation behavior

To change what happens to files that fail validation add an after_validation hook:

after_validation :dump_infected_files

def dump_infected_files
  if Array(errors.get(:content)).any? { |msg| msg =~ /A virus was found/ }
    content.content = errors.get(:content)
    save
  end
end

Regenerating the README TOC

Install the gh-md-toc tool, then ensure your README changes are up on GitHub, and then run:

gh-md-toc https://github.com/USERNAME/sufia/blob/BRANCH/README.md

That will print to stdout the new TOC, which you can copy into README.md, commit, and push.