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
  • Test app
  • Run tests
  • 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.

Test app

Generate the 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 tests

cd <sufia directory>
rake spec

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 are started on their own.

• How can I start a test instance of Solr? (DO NOT USE FOR PRODUCTION)

#  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

• 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
• How can I start a test instance of Fedora? (DO NOT USE FOR PRODUCTION)

#  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

• 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.

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>

8. cd .internal_test_app

9. solr_wrapper

10. 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.

11. Open a terminal

12. cd <sufia directory>

13. cd .internal_test_app

14. fcrepo_wrapper

15. Run the Rails server in development mode

16. Open a terminal

17. cd <sufia directory>

18. cd .internal_test_app

19. rails s

20. 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>
4. cd .internal_test_app
5. fcrepo_wrapper clean
6. 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.