About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

VuFind Documentation

Site Tools

You are here: start » videos » testing_1
Trace:
Warning: This page has not been updated in over over a year and may be outdated or deprecated.
videos:testing_1

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
videos:testing_1 [2021/05/07 16:19] – [Transcript] demiankatzvideos:testing_1 [2023/05/09 20:58] (current) – [Transcript] crhallberg
Line 1: Line 1:
 ====== Video 16: Testing, Part 1: Setting Up a Test Environment ====== ====== Video 16: Testing, Part 1: Setting Up a Test Environment ======
  
-The sixteenth VuFind instructional video discusses some tools for ensuring that VuFind's code is of high quality: style checkers/fixers and tests. After watching this video, you'll be able to automatically fix common problems with code style, spin up a brand new VuFind test instance with a single command line script, and run automated tests.+The sixteenth VuFind® instructional video discusses some tools for ensuring that VuFind®'s code is of high quality: style checkers/fixers and tests. After watching this video, you'll be able to automatically fix common problems with code style, spin up a brand new VuFind® test instance with a single command line script, and run automated tests.
  
 Video is available as an [[https://vufind.org/video/Testing1.mp4|mp4 download]] or through [[https://www.youtube.com/watch?v=69ocC-VALXY&feature=youtu.be|YouTube]]. Video is available as an [[https://vufind.org/video/Testing1.mp4|mp4 download]] or through [[https://www.youtube.com/watch?v=69ocC-VALXY&feature=youtu.be|YouTube]].
Line 54: Line 54:
 ===== Transcript ===== ===== Transcript =====
  
-// This is a computer-generated transcript; it will be corrected when time permits. //+Hello, and welcome to the first in our series of videos about testing VuFind. This month, my goal is to show you how to set up a VuFind test environment that will allow you to quickly create a running VuFind environment that you can test, and show you how to run some useful tools that will ensure that you're producing quality code and not breaking anything.
  
- hello and welcome to the first in our +There are many, many ways that you can set up a VuFind test environment, and so I don't claim that the way I'm going to show you is the only right way, but this is a method that has worked well for me and allows me to quickly and easily create and destroy test environments so I can try things out without worrying about impact from one experiment to another and so forth.
-series +
-of videos about testing viewfind +
-this month my goal is to show you how to +
-set up +
-a viewfind test environment that will +
-allow you to quickly create a +
-running viewfinder environment that you +
-can test +
-and show you how to run some useful +
-tools +
-that will ensure that you're producing +
-quality code and not breaking anything +
-there are many many ways that you can +
-set up a viewfind test environment +
-and so i don't claim that the way i'm +
-going to show you is the only right way +
-but this is a method that has worked +
-well for me and allows me to +
-quickly and easily create and destroy +
-test environments +
-so i can try things out without worrying +
-about +
-impact from one experiment to another +
-and so forth +
-the main prerequisite for getting all of +
-this going is just +
-having a system set up with viewfinds +
-prerequisites installed +
-so you'll want apache php +
-a database either mysql or postgres +
-and java so that you can run solar uh +
-one really easy way to get all of those +
-things is to just +
-install vufine's debian package and then +
-if you don't need it you can uninstall +
-it again but all those dependencies +
-will remain in place for the purposes of +
-today's demo +
-i'm actually using the same ubuntu +
-virtual machine i've been using for all +
-of the other tutorial videos +
-so this already has the debian package +
-installed +
-so all the prerequisites are there um +
-in real life i don't necessarily advise +
-doing testing on the same system as uh +
-you're actually running another +
-viewfinder instance +
-but for demonstration purposes with a +
-test only system +
-there's very little to lose anyway all +
-those disclaimers out of the way +
-here i am with my prerequisites already +
-installed +
-and all i want to do to get started is +
-make a fresh +
-clone of viewfind's git repository +
-into my home directory at the command +
-prompt so here i am at my home directory +
-i'm just going to run git clone +
-https github.com +
-viewfind org viewfind +
-and then this is going to just download +
-all of the latest +
-viewfind code which i can then use to +
-set up my test environment +
-and as has been discussed in past videos +
-there are a lot of different branches +
-within the git repository so you can +
-switch to different points in time and +
-test +
-different things but for today i'm just +
-going to test the default dev branch +
-which contains all of the latest +
-bleeding edge code +
-and usually when you're testing it makes +
-sense to be testing against +
-the latest things so now my git clone +
-has completed +
-so now i want to switch into the +
-directory that i've +
-just created by cloning the repository +
-so i cd viewfind i'm now in the viewfind +
-subdirectory of my personal home +
-directory +
-and i'm just going to run composer +
-install to get all of viewfinds +
-dependencies so this will install all of +
-the code that viewfind needs to run +
-as well as a number of the tools that we +
-are going to use +
-because when you run composer install by +
-default +
-it installs development dependencies as +
-well as production dependencies +
-and viewfinder is configured with a +
-whole bunch of useful development tools +
-that it will use to automate some tasks +
-so right now we are just downloading +
-solar which will take a few seconds +
-we are also of course going to need +
-solar in order to have an index +
-to test with so while we wait for this +
-to download i guess i can take a moment +
-to just talk about +
-why testing is important um +
-viewfind as a project has been in +
-development for +
-more than a decade now so there's been a +
-whole lot of change +
-and in order to make changes in the code +
-you have to have confidence +
-that the code will still work after +
-you've changed things +
-uh and over time it can get increasingly +
-difficult to do this kind of work by +
-hand +
-and so viewfind has a whole set of +
-automated tests built into it +
-that ensure that when code changes +
-functionality does not uh these tests +
-fall into +
-two main categories there are what we +
-call +
-unit tests which are just designed to +
-test +
-individual components of the software in +
-isolation +
-to make sure that they behave as +
-expected +
-and then we also have integration tests +
-which test the entire system to make +
-sure that all the pieces work together +
-as expected uh and +
-during the course of this video i'll +
-show you how to run both of those types +
-of tests +
-the unit tests because they're small and +
-isolated and simple +
-are pretty easy to run and they run very +
-quickly +
-the integration tests which actually +
-create a complete running viewfinder +
-environment +
-and use a web browser to navigate +
-through it and test all of the +
-interfaces +
-are a bit more complicated to set up and +
-take a lot more time to run +
-but the advantage of what i'm showing +
-you today +
-is that by setting up a handful of +
-scripts we can automate +
-all of this setup work and very easily +
-reproduce these tests +
-at will so if you're working on +
-changing something or refactoring code +
-you can +
-be reasonably confident that your +
-changes have worked and if you've +
-introduced a bug +
-the tests will help you find where +
-things are broken +
-i should also note that of course vue +
-finds tests are in no way +
-100 percent complete there are certainly +
-some gaps +
-so i'm also hoping that over the course +
-of this video series by showing you how +
-to write tests +
-which we'll cover next month it will be +
-possible for members of the community to +
-contribute back +
-additional tests increase our coverage +
-and further improve the stability of the +
-project +
-going forward another +
-aspect of of what our development tools +
-do in addition to testing +
-is that we have some tools that +
-verify the uniformity and quality of the +
-code that's being written +
-by applying consistent styling rules and +
-checking for things like +
-missing or incorrect comments i'm also +
-going to show you how to run those +
-and by doing that it's possible to avoid +
-some +
-problems when submitting changes to the +
-project +
-since a lot of these tests are run +
-automatically on all submissions +
-since this download appears to be taking +
-forever +
-i'm now going to cheat a little bit +
-because just as in a cooking show +
-i've already downloaded and set all of +
-this stuff up +
-and so i am just going to interrupt this +
-process +
-and get rid of my work in progress and +
-replace it +
-with the one i created earlier +
-so pretend that this all happened in +
-real time but +
-uh i was impatient so +
-here we are viewfind has been cloned +
-from git +
-composer has been run to install +
-everything +
-so i was just talking about style +
-checkers +
-and these are among the easiest things +
-to run so let me show you +
-two important ones one is called phpcs +
-fixer +
-and i can run this by typing vendor +
-slash +
-bin fing space php dash +
-cs dash fixer i'll show you what that +
-looks like +
-phpcs fixer is a tool that will +
-automatically +
-find and correct a number of style +
-issues +
-in php code it will do things like +
-ensure that white space is uniform in +
-some cases it can do +
-fairly advanced things like identify +
-overly complicated code and replace it +
-with a simpler version +
-so viewfind is set up with a number of +
-php cs fixer rules and we apply these to +
-all of the code that we commit to the +
-project and this just ensures that +
-things are readable +
-if you look at two files they use the +
-same style +
-and as i say some complicated bits of +
-code +
-are reduced to more readable simpler +
-code +
-i don't expect that this will find any +
-problems here because as i say we've +
-already +
-found and fixed all of the problems that +
-it detects but it's useful to have this +
-tool when you're working on new code +
-because you can run it +
-to ensure that anything you're adding or +
-changing doesn't introduce new problems +
-to the project you'll also notice that +
-when i ran this +
-i didn't run php cs fixer directly +
-i instead ran it through something +
-called fing +
-p-h-i-n-g thing +
-uh is a php build automation tool +
-which is inspired by ant which is a tool +
-used in +
-the java ecosystem and what fing does +
-is allow you to define a number of tasks +
-in an xml file +
-called build.xml a lot of the things i'm +
-going to show you today +
-are tasks that are defined in things +
-build.xml file +
-and this is just a convenient way to +
-centralize +
-all of your automated tasks in one way +
-and because of the way that the xml is +
-designed +
-it also allows some of this automation +
-to take place in a cross-platform way +
-so while i could certainly do something +
-like build a shell script to automate +
-this +
-then it would only work in linux but +
-with fing i can do the same things in +
-windows and in linux and in other places +
-and get the same results which is a nice +
-thing +
-in any case again this code checker is +
-taking quite a while and i know it's not +
-going to find any problems so i'm just +
-going to go ahead and interrupt it +
-and show you the build xml file briefly +
-just so you can see what this looks like +
-and because you might want to look +
-through it at some point to see what +
-other automated tasks are supported in +
-viewfind or to add new tasks of your own +
-so the xml file begins with a whole +
-bunch of properties which are all +
-settings that can be overridden and i'll +
-show you how to override those +
-in the near future but if you ever need +
-to change the behavior +
-of a thing task the first thing you can +
-do is look at these properties and see +
-if there's an existing setting +
-that will allow you to to accomplish +
-that +
-and then down below that there are a +
-number of targets with names +
-and these are all of the tasks that +
-thing can run for you +
-so for example if i search the file for +
-phpcs fixer +
-i can find here is that particular task +
-and it's just a couple of exec tags +
-which are running +
-commands for us and as you can see +
-by saying thing phpcs fixer +
-we then don't have to type a whole bunch +
-of additional +
-parameters and options so it's just a +
-time saver for +
-uh us the subject of style fixing +
-tasks available in fing i already told +
-you about php cs fixer +
-but there's also a tool called php code +
-sniffer +
-and this differs from phpcs fixer +
-in that it can find a number of problems +
-that can't be automatically fixed that +
-require human intervention +
-for example if you create a class or a +
-function but you don't put +
-appropriate comments documenting its +
-parameters +
-php code sniffer will identify that and +
-tell you that you need to add +
-the comments again this is just a +
-helpful way of ensuring +
-that any code you create is of high +
-quality +
-and if you want to run that it's a +
-matter of +
-running thing fender slash bin slash +
-fing and saying phpcs +
-dash console this particular task +
-is called phpcs-console because it's +
-designed to run +
-php code sniffer and output +
-the results it finds to the console +
-there are a couple of other tasks that +
-will run it and +
-output documents containing issues +
-instead +
-and these are used in automation but the +
-console version +
-is the most useful if you're just doing +
-this by hand and you want to check your +
-work +
-again in practice this takes a minute or +
-so to run +
-so i'm just going to interrupt it +
-because i know it's not going to +
-actually tell me anything +
-but if there were issues with your code +
-when it finished running it would give +
-you a report of which files and lines +
-have issues that need attention +
-in some cases it will also find +
-issues that can be repaired +
-automatically by a third tool +
-which is called phpcbf and as you might +
-guess +
-if you ever need to use that you can run +
-it uh with +
-vendor slash bin fing php +
-cbf which again will just take a few +
-seconds +
-and if it's able to fix your files it +
-will do so automatically +
-in any case though these code style +
-tools are useful +
-and are a way of introducing what fing +
-is and what it does but they are not the +
-main thing we're here to talk about +
-today +
-we're here to talk about testing so +
-let's get into that +
-as i mentioned earlier there are two +
-kinds of tests +
-with viewfind there are the simple unit +
-tests that test +
-individual software components and there +
-are also the integration tests +
-which test the entire system to make +
-sure that all the components are working +
-together +
-and as i said earlier running the unit +
-test is much easier and quicker +
-than setting up the whole integration +
-system so let's start +
-there running the unit test is just +
-another thing task we use +
-a tool called php unit which is a widely +
-used and very powerful testing framework +
-in fact even though php unit is in the +
-name we use phpunit for not just unit +
-tests but also the integration tests +
-and all of the tests are run in the same +
-way +
-the difference is that the tests will +
-detect +
-whether you have a full test environment +
-or not +
-and will run a different number of tests +
-depending on the circumstances +
-so right now all i've done is +
-check out viewfind's git repository and +
-install its dependencies with composer +
-i don't have the full environment +
-running so when i run +
-the php unit fast task in +
-thing what's going to happen here is +
-it's going to run a whole bunch of tests +
-it popped out a little error up there +
-which if you had paused to read it said +
-this is a normal error expected during +
-testing so it's safe to ignore it so +
-that's fine +
-but anyway for every unit test that it +
-runs it outputs a little dot +
-and so you can see it ran more than a +
-thousand tests +
-and then we get a bunch of s's which +
-indicates that some tests +
-were skipped and these are all the +
-integration tests +
-the test framework detected that +
-the full integration environment was not +
-available so it just skipped the tests +
-it couldn't run +
-so if you're ever working on building a +
-new component and you want to unit test +
-it +
-you can just write tests and run them +
-this way you don't need to worry about +
-the integration piece +
-until you're ready to test the whole +
-system because this is so fast +
-it's really useful during early stages +
-of software development +
-to just run unit tests and see if +
-anything is breaking +
-and save the integration testing for the +
-end +
-one other thing that i'd like to show +
-you at this stage +
-is that of course we skipped 166 tests +
-and i told you why +
-but suppose you don't want to take my +
-word for it +
-there is a way to get php unit to tell +
-you +
-uh why tests were skipped +
-let me show you how that works uh as i +
-mentioned +
-a fing has all of those properties which +
-you can override as needed +
-and the way that you do that is with the +
-minus capital d +
-switch at the command line so if i +
-say vendor slash bin slash +
-fing php unit fast +
-there's a property in thing called php +
-unit +
-underscore extra underscore params +
-which is a way to just pass through +
-additional parameters to the php unit +
-command +
-so i can set that equal to minus minus +
-verbose which will put php unit into +
-verbose mode +
-so it will provide more detailed +
-information +
-and now when i run the task it will +
-repeat what it did before but when it's +
-done running it's going to give me +
-a much more detailed report including an +
-explanation +
-of why all those tests were skipped +
-and it's all going to boil down to this +
-message +
-continuous integration not running +
-let me take a moment to talk about +
-continuous integration +
-continuous integration is simply the +
-process +
-of continually testing software +
-automatically +
-as it changes to detect problems +
-and so all of the things that i'm going +
-to show you for setting up a test +
-environment were actually +
-originally developed for use in +
-viewfind's continuous integration +
-environment we use continuous +
-integration in a couple of places +
-we have a standalone server running a +
-tool called +
-jenkins which is continually monitoring +
-the dev branch for changes and every +
-time code changes +
-it runs the full integration tests and +
-sends out an alert +
-if something has broken additionally +
-we use some lighter weight continuous +
-integration +
-integrated with github so that when +
-people open pull requests or make +
-changes +
-some lighter weight tests are run so we +
-detect style +
-problems or broken unit tests though we +
-don't run the full +
-integration suite at that time but in +
-any case the point of continuous +
-integration +
-is to be an early warning of potential +
-problems +
-the the goal is to set up robust tests +
-and then run them frequently so that if +
-something changes that breaks a test +
-you are immediately alerted to it and +
-can address it before it becomes a wider +
-more +
-systemic problem but in any case +
-all of you finds integration tests look +
-for some markers set up by the +
-continuous integration +
-startup to make sure that there's a +
-system in place that they can run within +
-and if there isn't they skip themselves +
-and give you that +
-continuous integration not running +
-message +
-so with that background out of the way +
-let's +
-actually set everything up so that we +
-can +
-run the integration tests which will +
-also have the side effect of giving us +
-a quick way to create a clean +
-viewfinder environment on demand if we +
-want to +
-test that something we're working on +
-works with an +
-out of the box installation and before i +
-proceed +
-let me just repeat a warning that i +
-think i implied earlier +
-never do this on a production system you +
-want to do your continuous integration +
-testing +
-on a test system in isolation from any +
-real data +
-the tests are going to actually create +
-and destroy databases +
-and solar indexes in order to set +
-everything up +
-and you really don't want to risk +
-accidentally destroying real data +
-because of something your tests did +
-there are safeties in place +
-in these tests to try to protect you +
-against such things +
-but don't take any chances do this in a +
-safe +
-isolated environment so with that out of +
-the way there are a few +
-steps of setup that need to be done +
-and some of them are oddly specific and +
-some of them are a bit laborious +
-but please bear with me because once +
-you've done all of this you +
-only have to do it once and then it will +
-save you enormous amounts of time +
-as you take advantage of testing in the +
-future +
-so the first thing that i need to do is +
-an apache +
-configuration change one of vufine's +
-integration tests +
-tests whether viewfind can correctly +
-handle records +
-that have ids with slashes in them and +
-by default +
-apache is configured to disallow slashes +
-in a url encoded format in a url +
-which is how viewfind allows access to +
-records with slashes in the ids +
-in a real world environment this usually +
-doesn't matter at all +
-but occasionally people want ids with +
-slashes and so this test +
-exists to ensure that that support +
-doesn't break +
-in the future and so we just have to set +
-up our system to allow it so that we can +
-run the test +
-and this is pretty simple we just need +
-to +
-edit the default +
-apache virtual host which uh in this +
-ubuntu environment +
-exists in etc apache 2 +
-site stash available 0 0 0-default +
-so i just need to go into this file +
-scroll down near the bottom +
-and inside the virtual host add the line +
-allow encoded slashes on +
-uh and this will make apache accept +
-uh slashes in ids in viewfind +
-and i'm also going to run system ctl +
-restart apache 2 to +
-reload that configuration and make sure +
-i didn't break anything +
-so apache is now ready for testing +
-uh the other thing that i need to do is +
-install +
-a browser automation tool of some sort +
-viewfind's integration tests support +
-either selenium +
-or google chrome running in headless +
-mode +
-and i strongly recommend google chrome +
-running in headless mode +
-because it's a lot less work to set up +
-all you have to do is install chrome and +
-set up a script +
-i'll show you the script part in the +
-moment +
-and i've already installed chrome on +
-this system so i'm not going to show you +
-that step +
-but it's as easy as going to google's +
-website +
-downloading the chrome package and +
-installing it +
-so we now have our software +
-prerequisites in place +
-apache is reconfigured chrome is +
-installed +
-so now we need to set up a handful of +
-shell scripts to +
-help automate some things and to store +
-some parameters +
-so we don't have to type the same stuff +
-over and over again +
-i'm also going to link to some +
-documentation from the uh +
-notes on this video when it's posted so +
-all of these scripts that i typed in +
-here will be available to you +
-so you don't have to just listen to me +
-and transcribe you can copy and paste +
-the first script i want to set up +
-uh is a to set up the environment +
-variables +
-that our test environment is going to +
-expect +
-so i'm going to create this in my home +
-directory +
-so i'm going to edit +
-tilde slash test env.sh +
-so the tilde slash means edit this file +
-inside my home directory +
-i'm calling it test env.sh because it +
-sets up my test environment +
-and i'm just going to put some exports +
-in here to set up the usual +
-viewfind environment variables so export +
-viewfind +
-home equals home slash ecats slash +
-viewfind +
-this is just the directory where my +
-viewfinder code +
-lives i'm going to export +
-viewfind localder equals +
-home decat viewfinder local +
-that will be where the local settings +
-will be stored +
-and i'm going to export view find +
-local modules equals nothing +
-because i don't have any custom code +
-modules +
-in my local test environment +
-now if i were setting up a test machine +
-that +
-only had this test environment in it +
-i could link this file into profile.d +
-and then just have these environment +
-variables set globally by default +
-and i never have to think about them +
-again but +
-if i'm in a situation where i have +
-multiple viewfind +
-instances on the same machine i find +
-that it's useful to have a different +
-shell script +
-for each environment so that when i want +
-to work with one +
-i can source the appropriate script to +
-get my environment set correctly +
-and then it will work right for what i'm +
-trying to do +
-so as i mentioned earlier i'm setting +
-this up +
-on the same box that i've used for past +
-tutorials +
-so we actually already have a viewfind +
-home +
-set so if i echo the view find home +
-variable +
-you'll see that it's currently set to +
-user local viewfind +
-when i'm running tests i don't want to +
-accidentally be messing with +
-that other instance of viewfind so i can +
-now just say +
-source tilde slash test env.sh +
-and this will load the correct +
-environment variables so now if i echo +
-that +
-viewfind home variable you can see that +
-it now is +
-viewfinder so again depending on how you +
-set this up +
-and where you do it you may or may not +
-need to have an environment script like +
-this as part of your strategy but i just +
-wanted to highlight that +
-it can be useful +
-the next thing i need to set up is a +
-script +
-for running chrome with all of the +
-parameters necessary +
-to run tests so i am going to create +
-another script in my home directory and +
-this one i'm going to call +
-chrome dash headless dot sh +
-and this is going to run chrome in a +
-mode +
-that it will allow it to be automated by +
-viewfinds tests +
-so i'm just gonna start my script with +
-the usual hash bang bin bash to show +
-that it's a bash script +
-and then i'm going to add +
-the google chrome command which runs the +
-chrome browser +
-i'm going to give it the minus minus +
-disable +
-gpu switch to disable hardware graphics +
-acceleration +
-because that's not relevant in headless +
-mode +
-and i'm going to add the headless mode +
-switch minus minus +
-headless which means that chrome will +
-run without actually displaying anything +
-graphically because for the purposes of +
-automated testing +
-we don't need to see anything we just +
-need the browser to +
-do the work and report on the results +
-then we need to do remote minus +
-debugging +
-minus address this is how you can set up +
-remote debugging allowing an external +
-program +
-to drive your browser for testing +
-purposes +
-i'm just going to set this to 0.0.0.0 +
-which will allow anyone to connect to it +
-and i'll trust in my firewalls to not +
-let people in from outside +
-but you could put a specific ip address +
-here +
-to ensure that only authorized people +
-are automating your browser +
-i also need to set minus minus remote +
-debugging dash port +
-equals 9222 to specify +
-uh which port is used to connect for +
-remote debugging +
-uh 9222 is the port that viewfinder is +
-configured to use but +
-you can use different ports with a bit +
-of setup if you need to for some reason +
-then i'm going to say minus minus window +
-dash size +
-equals quote 1366 comma +
-768 quote to set the window size to a +
-common widescreen +
-window size you could of course test in +
-different sizes +
-if you wanted to for example do +
-different tests for +
-responsive design in different modes you +
-could set the +
-browser window size in this way +
-finally i'm going to add minus minus +
-disable dash extensions +
-which will just prevent chrome +
-extensions from being loaded +
-since they might interfere with the +
-testing and we don't need them for what +
-we're trying to do here +
-so having saved all of that i am now +
-going to chmod +
-plus x my chrome headless dot sh +
-to make it executable so i can run that +
-script when i need to +
-now as i said that script is going to +
-run chrome in headless mode which is +
-great +
-for uh running tests quickly because it +
-blazes through when it doesn't have to +
-render any actual graphics +
-that being said sometimes it's more +
-interesting to be able to actually +
-watch the tests as they're running so i +
-am going to copy +
-my chrome headless dot sh to another +
-script which i'm going to call chrome +
-dash test mode dot +
-sh and i'm going to edit that +
-and i'm just going to take off the +
-headless switch +
-so this is going to create all the same +
-settings but this will let me actually +
-see what chrome is doing while the tests +
-run +
-which can be useful particularly if a +
-test is failing +
-and you want to see why so i have these +
-two scripts now i can start up chrome in +
-either +
-headless mode or test mode as i see fit +
-and i don't have to type all of those +
-many parameters anymore because they're +
-all just +
-saved in these convenient scripts all +
-right we're getting closer +
-there is just one more script that we +
-need to create +
-and this is going to be thing.sh +
-in my home directory we need this +
-because as i mentioned there are all of +
-these thing properties +
-that we need to be able to override +
-and it's just more convenient to do that +
-in the script so we don't have to type +
-them every time we run +
-tests so i start my script with the +
-usual hashbang bin bash because this is +
-a bash script +
-then i'm going to source home slash +
-decath test env.sh to ensure that every +
-time i run +
-thing it has the correct environment +
-variables set up +
-again there are different ways you can +
-do this but for this example +
-i'm putting my environment settings in +
-their own script and then i'm pulling +
-them in here +
-so there's a central place that manages +
-my environment +
-you might want to do this differently +
-setting the variables directly in here +
-or +
-or whatever do what what works best for +
-you this is just an example +
-and now the really exciting part +
-so first i use dollar view find home +
-slash vendor slash to run the thing +
-command +
-i can use the viewfind home variable +
-with confidence because i know it's just +
-been loaded in from my test env.sh +
-and now i need to add a whole bunch of +
-properties and i will explain them all +
-as i go +
-so first is minus capital d extra +
-underscore shutdown underscore cleanup +
-equals quote sudo +
-ch own minus capital r +
-d caps colon d cats +
-dollar sign view find home slash local +
-slash cash +
-end quote so what this does +
-is when we shut down our test +
-environment +
-thing supports this extra shutdown +
-cleanup property for running additional +
-commands +
-as part of the shutdown while we run our +
-tests +
-viewfind needs to make some of its cache +
-directories writeable by apache so that +
-the web interface will work correctly +
-but then because those cache directories +
-are owned by apache +
-when we try to shut things down and +
-clean everything up we won't have +
-permission to delete them +
-so this command changes the ownership of +
-the cache to my username +
-so that during shutdown i will be +
-allowed to delete everything +
-obviously you'll want to replace d caps +
-with your own username +
-if you're doing something similar in +
-your own environment +
-next property minus capital d +
-apache conf dir +
-apache conf der equals +
-quote slash etc apache 2 +
-slash comp dash enabled end quote +
-so as part of the setup process +
-for starting up the viewfind test +
-environment we need to actually +
-create a new apache configuration and +
-load that into apache that means the +
-process needs to know where apache +
-stores its configurations +
-this can vary from platform to platform +
-but +
-in ubuntu it's the etcetera apache 2 +
-conf enabled directory +
-so this property is just telling the +
-process +
-where it needs to put the generated +
-viewfind apache configuration +
-so that apache will load it and all of +
-the tests will have a working site +
-to interact with if you're in an +
-environment other than ubuntu you might +
-need to use a different value here +
-next is minus capital d apache ctl +
-equals sudo slash +
-etc init dot d slash apache 2 +
-end quote again this is related to the +
-startup of the system +
-uh in order for apache to recognize +
-a newly loaded configuration file it +
-needs to be restarted +
-and so the apache ctl property tells the +
-process +
-what command it can use to restart +
-apache +
-in this instance i'm just using sudo and +
-the init.d script for apache 2. +
-but there are a variety of ways you +
-could do this +
-also note that because i'm using sudo +
-here +
-when i start up the system it's going to +
-prompt me for my password +
-if you need to actually automate this +
-completely it requires some additional +
-configuration in your sudoers file +
-i'm not going to go into that now +
-because this is about doing things +
-manually rather than setting up +
-continuous integration +
-but feel free to ask me about that if +
-you're interested +
-all right next up minus capital d +
-mysql root pass +
-equals tutorial so viewfinder +
-startup process also needs to create a +
-new my sequel database which means that +
-it needs +
-access to the root account so +
-on this virtual machine test environment +
-i've set that to tutorial use a better +
-password in real life +
-but your script needs to pass the +
-password in +
-so that a database can be created for +
-the automated testing +
-next up minus capital d viewfinder url +
-equals http colon slash slash localhost +
-slash you find underscore test +
-so as i keep saying this test process is +
-actually going to create a running +
-instance of viewfind +
-and this property specifies the url +
-of that instance the process is actually +
-smart enough that it will +
-parse this and use it to generate an +
-appropriate configuration file so i +
-could replace +
-viewfind underscore test with anything i +
-like +
-and as long as it doesn't conflict with +
-something else that's running on the +
-system +
-it will work but i'm using viewfind test +
-in this example +
-finally minus capital d mink +
-underscore driver equals chrome uh +
-mync is the browser automation tool that +
-vue finds tests use +
-and as i mentioned earlier there are +
-several different ways you can do +
-browser automation +
-i recommended chrome so that's what i'm +
-specifying here but if you were using +
-selenium +
-you could also say selenium here and +
-then finally +
-i end this with dollar asterisk +
-so that any parameters we pass to the +
-thing.sh script will get added on the +
-end of this long command line +
-so this is just a wrapper around the +
-thing command that sets a whole bunch of +
-properties for us +
-so that we're ready to set up our test +
-environment and don't have to repeat +
-ourselves +
-so i'm going to save that i'm going to +
-chmod plus +
-x thing.sh in my home directory +
-and now we're ready to run thing +
-commands +
-there is just one last thing before we +
-can +
-get to the exciting parts of this and +
-that is +
-as i mentioned the process is going to +
-write some files +
-into the apache configuration directory +
-so we need to be sure that the user +
-running tests has permission to do that +
-i'm going to do that by putting my group +
-on the comp enabled directory and then +
-putting group write permission on that +
-directory +
-again there are a million ways you could +
-do this this is just a quick and easy +
-way +
-i don't claim that it's necessarily the +
-best +
-so sudo chgrp +
-d-cats slash etc slash apache2 +
-comp dash enabled +
-and sudo chmod g plus w +
-slash etc apache 2 comp +
-enabled we are now ready to run +
-our tests so first of all +
-let's start up chrome so that the +
-browser automation pieces will work +
-i'm going to actually use +
-chrometestmode.sh +
-instead of chromeheadless.sh so that you +
-can see the test running which is +
-more exciting i should put an ampersand +
-on the end of that command to run it in +
-the background +
-so i don't lose access to my command +
-prompt so now chrome is running +
-i'm just going to minimize that for the +
-moment get back to my prompt +
-the other thing i need to do because i'm +
-doing this +
-on a system where viewfinder is already +
-running +
-is i'm going to do sudo system ctl stop +
-viewfind so i don't want the viewfinder +
-instance that i set up in earlier +
-tutorials running and conflicting with +
-the one that my test +
-environment is going to set up if you're +
-doing this on a clean system you don't +
-have to do this step because there's +
-nothing there to stop +
-i'm just doing that so my demo doesn't +
-break on me +
-so now we're ready to create the test +
-environment +
-we run our tilde thing.sh +
-script with the startup +
-parameter and that is going to run +
-through +
-the whole automated startup process +
-which will take +
-probably about three minutes so we've +
-just started up solar +
-and now we're running through the +
-process of indexing +
-a whole set of test records so that +
-this test environment is actually +
-populated with data +
-which makes the tests more meaningful +
-and allows us to +
-actually try things out without having +
-to do the work of locating our own test +
-records +
-and putting them in as you can see while +
-these tests run +
-there's a directory in viewfind called +
-tests +
-data which contains a bunch of mark +
-files and all of those mark files are +
-going to get loaded into the index +
-if you want to add your own test records +
-for further testing you can just stick +
-them in that directory and this startup +
-process will index them for you +
-another thing of note is that some of +
-those test mark files +
-have accompanying dot properties files +
-that otherwise have the same file name +
-so like +
-mark authoritybibs.mrc.properties +
-if you want to index a particular set of +
-test records with +
-non-default indexer settings you can use +
-that naming convention +
-uh to set up some additional indexing +
-rules +
-and that's used in a few places to allow +
-us to create +
-sample records for specific features of +
-viewfind like +
-hierarchical facets hierarchical +
-collections +
-uh geographic data and so forth +
-it's perhaps also worth noting if you +
-are running this in a virtual machine +
-like i +
-am that the resources you give to your +
-vm can significantly impact the speed of +
-this process +
-on physical hardware that i was using +
-previously this whole process took about +
-a minute and a half +
-on this particular vm it takes about +
-three minutes usually +
-it might be a little slower now because +
-my system is using additional resources +
-to stream and record this +
-but in any case i found that +
-by tuning my vm to use half of my system +
-ram +
-and also uh four cpus +
-i got much better results than when +
-using fewer resources +
-with with only one cpu it was taking +
-about 10 minutes +
-and we're done we built the browse index +
-took about five minutes +
-so we now have a running instance of +
-viewfind +
-and i can prove that by going to chrome +
-going to localhost you find +
-underscore test +
-and as you can see at the url i +
-specified in my script +
-i have a running instance of viewfind if +
-i do a search +
-it has 320 records in it with a bunch of +
-facets showing +
-which mark files they came from and so +
-forth +
-so if you just want a viewfinder that +
-you can play with and try to break +
-uh as you can see you create a couple +
-scripts you wait five minutes +
-you've got it it's quicker than having +
-to do all the installation work by hand +
-and if you break it you can just destroy +
-it and build a new one in five more +
-minutes +
-so that's the advantage to having this +
-this whole process +
-but now let's let's look at the test +
-which is even more fun +
-so if i go here and i say thing +
-phpunit fast and again i'm using the +
-thing.sh in my home directory for this +
-it's going to run through the tests and +
-it's first going to run the same unit +
-test as before +
-but then it's going to get down to the +
-integration part +
-right about now and now look +
-chrome has just popped up and it's doing +
-stuff it's creating +
-a user and it is +
-checking that it can log in and out and +
-so forth +
-and if i allowed this to run without +
-interruption +
-it would do this for about 15 minutes +
-running through +
-a whole lot of different tasks and +
-reporting if anything broke +
-of course i don't want to make you sit +
-and watch this browser automatically +
-running through for 15 minutes so i'm +
-going to interrupt the process with +
-control c and stop it +
-but i have successfully demonstrated how +
-to +
-set up your test environment and run +
-your tests +
-a couple of quick notes uh as i +
-mentioned +
-i i like to run the test with this php +
-unit +
-fast task and it's called phpunit fast +
-because it just runs the tests +
-it doesn't generate any reports or +
-output +
-if i ran just php unit without the fast +
-part +
-it would create a number of report files +
-that are used by continuous integration +
-tools +
-uh so we just saved some time by +
-skipping that +
-the thing about php unit fast though is +
-that it will run +
-every single test every time even if +
-some of the tests fail +
-if you want to just find out why tests +
-are failing as quickly as possible +
-you can run php unit faster and it will +
-run tests +
-until the first failure and then +
-immediately stop and report why it +
-failed +
-so that can save you some time if you're +
-struggling with an issue +
-another thing that is useful to know +
-is that all of these php unit tasks +
-except the minus d php unit +
-extra params switch +
-and if you specify the full path to a +
-unit test +
-file then it will only run that one test +
-or if you specify the path to a +
-directory it will only run the tests +
-in that directory so again if you're +
-trying to test something specific you +
-don't have to sit through the entire +
-15-minute test suite +
-to wait for that test to run you can get +
-there immediately +
-uh and next month when i show you how to +
-write tests +
-i'll show you how these are structured +
-how to find the tests you need +
-and so forth since we're short on time i +
-won't do that right now +
-so the last thing to show you is that +
-when we're all done +
-we can run thing.sh shutdown +
-and this is going to actually just +
-delete +
-all of the test data and all of the +
-configurations and shut everything down +
-and now our entire test environment is +
-gone +
-so when we're done if we don't want to +
-be taking up those system resources +
-running all those things again +
-this will take care of it however +
-uh there's one important thing as a last +
-little detail that i want to show you +
-which is that the shutdown task +
-actually deletes all of your composer +
-dependencies along with everything else +
-which means that it has deleted thing +
-so that means that now if i try to start +
-the system up again +
-it's not going to work because it can't +
-find fing anymore +
-so i'm going to add a little bit more +
-intelligence +
-to my thing.sh script in my home +
-directory to solve this problem +
-uh this assumes that you have composer +
-installed +
-globally on your system which in this +
-instance i do +
-but if i just add before my thing +
-command +
-if bracket exclamation point minus e +
-dollar sign you find home slash +
-vendor close bracket in other words if +
-the vendor directory in my viewfind home +
-directory does not exist +
-then cd you find home +
-composer install fi to end my +
-if so this little check in our script +
-will find out +
-if you haven't installed your composer +
-dependencies yet which you need to do +
-for thing to work it will automatically +
-reinstall them for you +
-so now if i say thing.sh startup again +
-it's going to automatically reinstall my +
-dependencies for me +
-and then it will start up the system +
-again +
-so that's everything i wanted to show +
-you this month +
-hopefully you now see how you can set up +
-an environment for testing do you find +
-uh disposing of that environment when +
-you're done +
-and maybe you've also learned a little +
-bit more about style checking tools +
-along the way if you have any questions +
-by all means let me know i'm happy to +
-answer them +
-so thanks again and i look forward to +
-next month when we can talk about +
-actually writing some brand new tests +
-talk to you then+
  
 +The main prerequisite for getting all of this going is just having a system set up with VuFind's prerequisites installed, so you'll want a patchy PHP database, either MySQL or Postgres and Java so that you can run Solr. One really easy way to get all of those things is to just install VuFind's Debian package, and then if you don't need it, you can uninstall it again, but all those dependencies will remain in place.
 +
 +For the purposes of today's demo, I'm actually using the same Ubuntu virtual machine I've been using for all of the other tutorial videos, so this already has the Debian package installed, so all the prerequisites are there. In real life, I don't necessarily advise doing testing on the same system as you're actually running another VuFind instance, but for demonstration purposes with a test only system, there's very little to lose.
 +
 +Anyway, all those disclaimers out of the way. Here I am with my prerequisites already installed, and all I want to do to get started is make a fresh clone of VuFind's Git repository into my home directory at the command prompt. So here I am at my home directory, I'm just going to run ''git clone https://github.com/vufind-org/vufind'', and then this is going to just download all of the latest VuFind code, which I can then use to set up my test environment. And as has been discussed in past videos, there are a lot of different branches within the Git repository, so you can switch to different points in time and test different things.
 +
 +But for today, I'm just going to test the default dev branch, which contains all of the latest leading edge code. And usually when you're testing, it makes sense to be testing against the latest things. So now my Git clone has completed. So now I want to switch into the directory that I've just created by cloning the repository. So I see the VuFind. I'm now in the VuFind sub directory of my personal home directory. And I'm just going to run ''composer install'' to get all of VuFind's dependencies. So this will install all of the code that VuFind needs to run, as well as a number of the tools that we are going to use, because when you run ''composer install'', by default, it installs development dependencies as well as production dependencies. And VuFind is configured with a whole bunch of useful development tools that it will use to automate some tasks.
 +
 +So right now we are just downloading Solr, which will take a few seconds. We're also of course going to need Solr in order to have an index to test with. So while we wait for this to download, I guess I can take a moment to just talk about why testing is important. VuFind as a project has been in development for more than a decade now. So there's been a whole lot of change. And in order to make changes in the code, you have to have confidence that the code will still work after you've changed things. And over time, it can get increasingly difficult to do this kind of work by hand. And so VuFind has a whole set of automated tests built into it, that ensure that when code changes functionality does not. These tests fall into two main categories. There are what we call unit tests, which are just designed to test individual components of the software in isolation to make sure that they behave as expected. And then we also have integration tests, which test the entire system to make sure that all the pieces work together as expected. And during the course of this video, I'll show you how to run both of those types of tests. The unit tests, because they're small and isolated and simple, are pretty easy to run. And they run very quickly.
 +
 +The integration tests, which actually create a complete running VuFind environment and use a web browser to navigate through it and test all of the interfaces are a bit more complicated to set up and take a lot more time to run. But the advantage of what I'm showing you today is that by setting up a handful of scripts, we can automate all of this setup work and very easily reproduce these tests at will. So if you're working on changing something or refactoring code, you can be reasonably confident that your changes have worked. And if you've introduced a bug, the tests will help you find where things are broken. I should also note that, of course, if you find tests are in no way 100% complete, there are certainly some gaps. So I'm also hoping that over the course of this video series, by showing you how to write tests, which will cover next month, it will be possible for members of the community to contribute back additional tests, increase our coverage, and further improve the stability of the project going forward.
 +
 +Another aspect of what our development tools do, in addition to testing, is that we have some tools that verify the uniformity and quality of the code that's being written by applying consistent styling rules and checking for things like missing or incorrect comments. I'm also going to show you how to run those. And by doing that, it's possible to avoid some problems when submitting changes to the project, since a lot of these tests are run automatically on all submissions.
 +
 +Since this download appears to be taking forever, I'm not going to cheat a little bit, because just as in a cooking show, I've already downloaded and set all of this stuff up. And so I am just going to interrupt this process and get rid of my work in progress and replace it with the one I created earlier. So pretend that this all happened in real time, but I was impatient. So.
 +
 +Here we are. VuFind has been cloned from Git, composer has been run to install everything. So I was just talking about style checkers. And these are among the easiest things to run. Let me show you two important ones. One is called PHP CS Fixer. And I can run this by typing ''vendor/bin/phing php-cs-fixer''.
 +
 +I'll show you what that looks like. PHP CS Fixer is a tool that will automatically find and correct a number of style issues in PHP code. It will do things like ensure that white space is uniform. In some cases, it can do fairly advanced things like identify overly complicated code and replace it with a simpler version. So if you find a setup with a number of PHP CS Fixer rules, and we apply these to all of the code that we commit to the project. And this just ensures that things are readable. And as I say, some complicated bits of code are reduced to more readable simpler code. I don't expect that this will find any problems here, because as I say, we've already found and fixed all of the problems that it detects, but it's useful to have this tool when you're working on new code because you can run it to ensure that anything you're adding or changing doesn't introduce new problems to the project. You'll also notice that when I ran this, I didn't run PHP CS Fixer directly. I instead ran it through something called "Phing". Phing is a PHP build automation tool, which is inspired by Ant, which is a tool used in the Java ecosystem. And what thing does is allow you to define a number of tasks in an XML file called ''build.xml''. A lot of the things I'm going to show you today are tasks that are defined in things ''build.xml'' file, and this is just a convenient way to centralize all of your automated tasks in one way. Because of the way that the XML is designed, it also allows some of this automation to take place in a cross-platform way. So, while I could certainly do something like build a shell script to automate this, then it would only work in Linux. But with Phing, I can do the same things in Windows and in Linux and in other places and get the same results, which is a nice thing. In any case, again, this code checker is taken quite a while, and I know it's not going to find any problems, so I'm just going to go ahead and interrupt it and show you the ''build.xml'' file briefly just so you can see what this looks like.
 +
 +And because you might want to look through it at some point to see what other automated tasks are supported in view, find or to add new tasks of your own. So the ''build.xml'' file begins with a whole bunch of properties, which are all settings that can be overridden and I'll show you how to override those in the near future. But if you ever need to change the behavior of a thing task, the first thing you can do is look at these properties and see if there's an existing setting that will allow you to to accomplish that.
 +
 +And then down below that, there are a number of targets with names and these are all of the tasks that Phing can run for you. So, for example, if I search the file for "php-cs-fixer". I can find here is that particular task. And it's just a couple of exec tags which are running commands for us. And as you can see, by saying ''phing php-cs-fixer'', we then don't have to type a whole bunch of additional parameters and options. So it's just a time saver for us.
 +
 +On the subject of style-fixing tasks available in Phing, I already told you about PHP CS Fixer. But there's also a tool called PHP code sniffer. And this differs from PHP CS Fixer in that it can find a number of problems that can't be automatically fixed that require human intervention. For example, if you create a class or a function, but you don't put appropriate comments documenting its parameters, PHP code sniffer will identify that and tell you that you need to add the comments. Again, this is just the helpful way of ensuring that any code you create is of high quality. And if you want to run that, it's a matter of running ''vendor/bin/phing phpcs-console''. This particular task is called "phpcs-console" because it's designed to run PHP code sniffer and output the results it finds to the console. There are a couple of other tasks that will run it and output documents containing issues instead. And these are used in automation, but the console version is the most useful if you're just doing this by hand and you want to check your work.
 +
 +Again, in practice, this takes a minute or so to run so I'm just going to interrupt it because I know it's not going to actually tell me anything. But if there were issues with your code when it finished running it would give you a report of which files and lines have issues that need attention. In some cases, it will also find issues that can be repaired automatically by a third tool, which is called PHP CBF. And as you might guess, if you ever need to use that you can run it with ''vendor/bin/phing phpcbf'', which again we'll just take a few seconds and if it's able to fix your files, it will do so automatically.
 +
 +In any case, these code style tools are useful and are a way of introducing what Phing is and what it does, but they are not the main thing we're here to talk about today we're here to talk about testing so let's get into that. As I mentioned earlier, there are two kinds of tests with you find there are the simple unit tests that test individual software components and there are also the integration tests which test the entire system to make sure that all the components are working together. And as I said earlier, running the unit tests is much easier and quicker than setting up the whole integration system so let's start there.
 +
 +Running the unit tests is just another thing task. We use a tool called PHPUnit which is a widely used and very powerful testing framework. In fact, even though PHPUnit is in the name we use PHPUnit for not just unit tests but also the integration tests and all of the tests are run in the same way. The difference is that the tests will detect whether you have a full test environment or not and will run a different number of tests depending on the circumstances. So right now all I've done is check out a few finds get repository and install its dependencies with composer. We have the full environment running so when I run the "phpunitfast" task in thing, what's going to happen here is it's going to run a whole bunch of tests. It popped out a little error up there which if you had paused to read it said "this is a normal error expected during testing so it's safe to ignore it", so that's fine.
 +
 +Anyway, for every unit test that it runs it outputs a little dot and so you can see it ran more than a thousand tests. And then we get a bunch of S's which indicates that some tests were skipped and these are all the integration tests the test framework detected that the full integration environment was not available so it just skipped the tests it couldn't run. If you're ever working on building a new component and you want to unit test it, you can just write tests and run them this way you don't need to worry about the integration piece until you're ready to test the whole system. Because this is so fast it's really useful during early stages of software development to just run unit tests and see if anything is breaking and save the integration testing for the end. So the thing that I'd like to show you at this stage is that of course we skipped 166 tests and I told you why, but suppose you don't want to take my word for it. There is a way to get PHPUnit to tell you why tests were skipped. Let me show you how that works. As I mentioned, a thing has all of those properties, which you can override as needed. And the way that you do that is with ''-D'' switch at the command block. So if I say ''vendor/bin/phing phpunitfast''. There's a property in thing called PHPUnit_extra_programs, which is a way to just pass through additional parameters to the PHPUnit command. I can set that equal to --verbose, which will put PHPUnit into verbose mode, so it will provide more detailed information. And now when I run the task, it will repeat what it did before, but when it's done running it's going to give me a much more detailed report, including an explanation of why all those tests were skipped. And it's all going to boil down to this message, continuous integration, not running. Let me take a moment to talk about continuous integration. Continuous integration is simply the process of continually testing software automatically as it changes to detect problems. So all of the things that I'm going to show you for setting up a test environment where actually originally developed for use in VuFind's continuous integration environment.
 +
 +We use continuous integration in a couple of places. We have a standalone server running a tool called Jenkins, which is continually monitoring the dev branch for changes and every time code changes. It runs the full integration tests and sends out an alert if something has broken. Additionally, we use some lighter weight continuous integration integrated with GitHub, so that when people open pull requests or make changes, some lighter weight tests are run, so we detect style problems or broken unit tests that we don't run the full integration suite at that time. But in any case, the point of continuous integration is to be an early warning of potential problems. The goal is to set up robust tests and then run them frequently so that if something changes that breaks the test, you are immediately alerted to it and can address it before it becomes a wider more systemic problem. In any case, all of you find integration tests look for some markers set up by the continuous integration startup to make sure that there's a system in place that they can run within. And if there isn't, they skip themselves and give you that continuous integration not running message. So, with that background out of the way, let's actually set everything up so that we can run the integration tests, which will also have the side effect of giving us a quick way to create a clean VuFind environment on demand if we want to test that something we're working on works within out of the box installation. And before I proceed, let me just repeat a warning that I think I implied earlier never do this on a production system. You want to do your continuous integration testing on a test system in isolation from any real data, the tests are going to actually create and destroy databases and Solr indexes in order to set everything up. You really don't want to risk accidentally destroying real data because of something your tests did. There are safeties in place in these tests to try to protect you against such things, but don't take any chances do this in a safe isolated environment. There are a few steps of setup that need to be done and some of them are oddly specific and some of them are a bit laborious, but please bear with me because once you've done all of this, you only have to do it once and then it will save you enormous amounts of time as you take advantage of testing in the future.
 +
 +So the first thing that I need to do is in Apache configuration change. One of VuFind's integration tests test whether VuFind can correctly handle records that have IDs with slashes in them. And by default Apache is configured to disallow slashes in a URL encoded format in a URL, which is how VuFind allows access to records with slashes in the IDs. This usually doesn't matter at all, but occasionally people want IDs with slashes and so this test exists to ensure that that support doesn't break in the future. And so we just have to set up our system to allow it so that we can run the test. It's pretty simple. We just need to edit the default Apache virtual host, which in this Ubuntu environment exists in et cetera Apache to site stash available. zero zero dash default dot com. So I just need to go into this file scroll down near the bottom and inside the virtual host add the line allow encoded slashes on. And this will make Apache accept slashes in IDs in VuFind. And I'm also going to run ''systemctl restart apache2'' to reload that configuration and make sure I didn't break anything.
 +
 +So Apache is now ready for testing. The other thing that I need to do is install a browser automation tool of some sort VuFind's integration tests support either Selenium or Google Chrome running in headless mode. And I strongly recommend Google Chrome running in headless mode because it's a lot less work to set up. All you have to do is install chrome and set up a script. I'll show you the script part in the moment. And I've already installed Chrome on this system. So I'm not going to show you that step, but it says easy as going to Google's website downloading the Chrome package and installing it. So we now have our software prerequisites in place. Apache is reconfigured Chrome is installed. So now we need to set up a handful of shell scripts to help automate things into stores and parameters. So we don't have to type the same stuff over and over again. We're also going to link to some documentation from the notes on this video when it's posted. So all of these scripts that I typed in here will be available to you that you don't have to just listen to me and transcribe you can copy and paste.
 +
 +The first script I want to set up is to set up the environment variables that our test environment is going to expect. So I'm going to create this in my home directory. So I'm going to edit ''~/testenv.sh''. So the ''~/'' means edit this file inside my home directory. I'm calling it ''testenv.sh'' because it sets up my test environment. And I'm just going to put some exports in here to set up the usual VuFind environment variables. So ''export VUFIND_HOME=/home/dkatz/vufind'' this is just the directory where my VuFind code lives. I'm going to ''export VUFIND_LOCAL_DIR=/home/dkatz/vufind/local'' that will be where the local settings will be stored. I'm going to ''export VUFIND_LOCAL_MODULES='' (nothing) because I don't have any custom code modules in my local test environment. Now, if I were setting up a test machine that only have this test environment in it, I could link this file into ''profile.d'' and then just have these environment variables set globally by default and I never have to think about them again. But if I'm in a situation where I have multiple VuFind instances on the same machine. I find that it's useful to have a different shell script for each environment so that when I want to work with one, I can source the appropriate script to get my environment set correctly, and then it will work right for what I'm trying to do. So as I mentioned earlier, I'm setting this up on the same box that I've used for past tutorials, so we actually already have a VuFind home set so if I echo the VuFind home variable, you'll see that it's currently set to user local VuFind. I don't want to accidentally be messing with that other instance of VuFind, so I can now just say ''source ~/testenv.sh'' and this will load the correct environment variables. So now if I echo that VuFind home variable, you can see that it now is ''/home/dkatz/vufind''. So again, depending on how you set this up and where you do it, you may or may not need to have an environment script like this as part of your strategy, but I just wanted to highlight that it can be useful.
 +
 +The next thing I need to set up is a script for running chrome with all of the parameters necessary to run tests. So I'm going to create another script in my home directory and this one I'm going to call chrome dash headless dot sh. And this is going to run chrome in a mode that it will allow it to be automated by VuFind tests.
 +
 +So I'm just going to start my script with the usual ''#!/bin/bash'' to show that it's a bash script and then I'm going to add the ''google-chrome'' command which runs the Chrome browser. And to give it the ''--disable-gpu'' switch to disable hardware graphics acceleration because that's not relevant in headless mode. And I'm going to add the headless mode switch, ''--headless'', which means that Chrome will run without actually displaying anything graphically. And then we need to do the purposes of automated testing. We don't need to see anything. We just need the browser to do the work and report on the results.
 +
 +Then we need to do ''--remote-debugging-address=''. This is how you can set up remote debugging, allowing an external program to drive your browser for testing purposes. And set this to ''0.0.0.0'', which will allow anyone to connect to it. And I'll trust in my firewall is to not let people in from outside. But you could put a specific IP address here to ensure that only authorized people are automating your browser.
 +
 +We also need to set ''--remote-debugging-port=9222'' to specify which port is used to connect for remote debugging. 9222 is the port that VuFind is configured to use, but you can use different ports with a bit of setup if you need to for some reason.
 +
 +Then I'm going to say ''--window=size="1366,768"'' quote to set the window size to a common widescreen window size. You could of course test in different sizes if you wanted to, for example, do different tests for responsive design in different modes, you could set the browser window size in this way.
 +
 +Finally, I'm going to add ''--disable-extensions'', which will just prevent chrome extensions from being loaded, since they might interfere with the testing and we don't need them for what we're trying to do here.
 +
 +So having saved all of that I am now going to ''chmod +x ~/chrome-headless.sh'' to make it executable, so I can run that script when I need to. Now, as I said, that script is going to run chrome in headless mode, which is great for running tests quickly because it blazes through when it doesn't have to render any actual graphics that being said, sometimes it's more interesting to be able to actually watch the tests as they're running.
 +
 +// Complete ~/chrome-headless.sh: //
 +
 +<code bash>
 +#!/bin/bash
 +google-chrome --disable-gpu --headless --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 --window=size="1366,768" --disable-extensions</code>
 +
 +So I am going to copy my ''chrome-headless.sh'' to another script, which I'm going to call ''chrome-testmode.sh''. And I'm going to edit that. And I'm just going to take off the headless switch, so this is going to create all the same settings, but this will let me actually see what chrome is doing while the tests run, which can be useful, particularly if the test is failing and you want to see why.
 +
 +
 +// Complete ~/chrome-testmode.sh: //
 +
 +<code bash>
 +#!/bin/bash
 +google-chrome --disable-gpu --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 --window=size="1366,768" --disable-extensions</code>
 +
 +So I have these two scripts now I can start up chrome in either headless mode or test mode, as I see fit and I don't have to type all of those many parameters anymore because they're all just saved in these convenient scripts. Alright, we're getting closer there is just one more script that we need to create, and this is going to be phing.xml in my home directory. We need this because, as I mentioned, there are all of these Phing properties that we need to be able to override and it's just more convenient to do that in the script, so we don't have to type them every time we run tests.
 +
 +So I start my script with the usual ''#!/bin/bash'' because this is a bash script, then I'm going to ''source /home/dkatz/testenv.sh'' to ensure that every time I run thing, it has the correct environment variables set up again there are different ways you can do this. But for this example I'm putting my environment settings in their own script and then I'm pulling them in here so there's a central place that manages my environment, you might want to do this differently setting the variables directly in here or whatever do what works best for you, this is just an example.
 +
 +The really exciting part so first I use ''$VUFIND_HOME/vendor/bin/phing'' to run the thing command, I can use the $VUFIND_HOME variable with confidence because I know it's just been loaded in from my ''testenv.sh''. And now I need to add a whole bunch of properties and I will explain them all as I go. So first ''-Dextra_shut down_cleanup="sudo chown -R dkatz:dkatz $VUFIND_HOME/local_cache"''. So what this does is when we shut down our test environment things supports this extra shut down cleanup property for running additional commands as part of the shutdown. While we run our tests view find needs to make some of its cash directories writable by Apache so that the web interface will work correctly. But then because those cash directories are owned by Apache when we try to shut things down and clean everything up we won't have permission to delete them. So this command changes the ownership of the cash to my username so that during shutdown I will be allowed to delete everything obviously you'll want to replace decaps with your own username if you're doing something similar in your own environment.
 +
 +Next ''-Dapacheconfdir="/etc/apache2/conf-enabled"''. As part of the setup process for starting up the view find test environment we need to actually create a new Apache configuration and load that into Apache. That means the process needs to know where Apache stores its configurations. This can vary from platform to platform, but in Ubuntu it's the ''/etc/apache2/conf-enabled'' directory. So this property is just telling the process where it needs to put the generated view find Apache configuration so that Apache will load it and all of the tests will have a working site to interact with. If you're in an environment other than Ubuntu you might need to use a different value here.
 +
 +Next is ''-Dapachectl="sudo /etc/init.d/apache2"''. Again, this is related to the startup of the system. In order for Apache to recognize a newly loaded configuration file, it needs to be restarted. And so the Apache CTL property tells the process what command it can use to restart Apache. In this instance I'm just using ''sudo'' and the ''init.d'' script for Apache to, but there are a variety of ways you could do this. Also note that because I'm using ''sudo'' here when I start up the system it's going to prompt me for my password. If you need to actually automate this completely, it requires some additional configuration in your ''sudoers'' file. I'm not going to go into that now because this is about doing things manually rather than setting up continuous integration, but feel free to ask me about that if you're interested.
 +
 +Next up ''-Dmysqlrootpass=tutorial''. So VuFind startup process also needs to create a new MySQL database, which means that it needs access to the root account. So on this virtual machine test environment I've set that to tutorial - use a better password in real life - but your script needs to pass the password in so that a database can be created for the automated testing.
 +
 +Next up ''-Dvufindurl=http://localhost/vufind_test''. So, as I keep saying this test process is actually going to create a running instance of VuFind and this property specifies the URL of that instance. The process is actually smart enough that it will parse this and use it to generate an appropriate configuration file. So I could replace ''vufind_test'' with anything I like and as long as it doesn't conflict with something else that's running on the system, it will work. But I'm using ''vufind_test'' in this example.
 +
 +Finally, ''-Dmink_driver=chrome''. I think is the browser automation tool that VuFind tests use. And as I mentioned earlier, there are several different ways you can do browser automation. I recommended chrome so that's what I'm specifying here, but if you were using Selenium, you could also say Selenium here.
 +
 +Finally, I end this with ''$\*'' so that any parameters we passed to the thing.xml script will get added on the end of this long command line.
 +
 +This is just a wrapper around the thing command that sets a whole bunch of properties for us so that we're ready to set up our test environment and don't have to repeat ourselves. So I'm going to save that I'm going to ''chmod +x ~/phing.sh'' and now we're ready to run thing commands.
 +
 +There is just one last thing before we can get to the exciting parts of this. And that is, as I mentioned, the process is going to write some files into the Apache configuration directory. I need to be sure that the user running tests has permission to do that. I'm going to do that by putting my group on the confidential directory and then putting group right permission on that directory. There are a million ways you could do this. This is just a quick and easy way. I don't claim that it's necessarily the best. So ''sudo chgrp dkatz /etc/apache2/conf-enabled'' and ''sudo chmod g+w /etc/apache2/conf-enabled''. We are now ready to run our tests.
 +
 +So first of all, let's start up Chrome so that the browser automation pieces will work. I'm going to actually use ''~/chrome-testmode.sh'' instead of ''~/chrome-headless.sh'' so that you can see the test running which is more exciting. I should put an ampersand on the end of that command to run it in the background so I don't lose access to my command prompt. So now Chrome is running. I'm just going to minimize that for the moment. Get back to my prompt. The other thing I need to do because I'm doing this on a system where VuFind is already running is I'm going to do ''sudo systemctl stop vufind''. So I don't want the VuFind instance that I set up in earlier tutorials running and conflicting with the one that my test environment is going to set up. If you're doing this on a clean system, you don't have to do this step because there's nothing there to stop. I'm just doing that so my demo doesn't break on me.
 +
 +So now we're ready to create the test environment. We run our ''~/phing.sh'' script with the ''startup'' parameter and that is going to run through the whole automated startup process which will take probably about three minutes.
 +
 +So we've just started up Solr and now we're running through the process of indexing a whole set of test records so that this test environment is actually populated with data which makes the tests more meaningful and allows us to actually try things out without having to do the work of locating our own test records and putting them in.
 +
 +As you can see while these tests run there's a directory in VuFind called ''/tests/data'' which contains a bunch of MARC files and all of those MARC files are going to get loaded into the index. If you want to add your own test records for further testing you can just stick them in that directory and this startup process will index them for you.
 +
 +Another thing of note is that some of those test MARC files have accompanying ''.properties'' files that otherwise have the same file name so like ''marc-authoritybibs.mrc.properties''. If you want to index a particular set of test records with non default index or settings you can use that naming convention to set up some additional indexing rules. And that's used in a few places to allow us to create sample records for specific features of VuFind like hierarchical facets hierarchical collections geographic data and so forth.
 +
 +It's perhaps also worth noting if you are running this in a virtual machine like I am that the resources you give to your VM can significantly impact the speed of this process on physical hardware that I was using previously this whole process took about a minute and a half. In particular VM it takes about three minutes usually it might be a little slower now because my system is using additional resources to stream and record this. But in any case, I found that by tuning my VM to use half of my system RAM and also for CPUs I got much better results than when using fewer resources with with only one CPU.
 +
 +And we're done we built the browse index took about five minutes, so we now have a running instance of VuFind, and I can prove that by going to Chrome going to http:/localhost/vufind_test. And you can see after URL I specified in my script I have a running instance of VuFind if I do a search it has 320 records in it with a bunch of facets showing which MARC files they came from and so forth.
 +
 +If you want of you find that you can play with and try to break, as you can see you create a couple scripts you wait five minutes you've got it it's quicker than having to do all the installation work by hand. And if you break it you can just destroy it and build a new one in five more minutes so that's the advantage to having this this whole process, but now let's let's look at the test which is even more fun.
 +
 +If I go here and I say ''~/phing.sh phpunitfast'' and again I'm using the thing.xml in my home directory for this it's going to run through the tests and it's first going to run the same unit test as before, but then it's going to get down to the integration part. Right about now. And now look Chrome has just popped up and it's doing stuff! It's creating a user! And it is checking that it can log in and out and so forth! If I allowed this to run without interruption it would do this for about 15 minutes running through a whole lot of different tasks I'm reporting if anything broke. Of course, I don't want to make you sit and watch this browser automatically running through for 15 minutes so I'm going to interrupt the process with control C and stop it, but I have successfully demonstrated how to set up your test environment and run your tests.
 +
 +A couple of quick notes, as I mentioned, I like to run the test with this ''phpunitfast'' task and it's called ''phpunitfast'' because it just runs the tests it doesn't generate any reports or output. If I ran just ''phpunit'' without the fast part, it would create a number of report files that are used by continuous integration tools. So we just saved some time by skipping that the thing about ''phpunitfast'', though, is that it will run every single test every time, even if some of the tests fail. If you want to just find out why tests are failing as quickly as possible, you can run ''phpunitfaster'', and it will run tests until the first failure and then immediately stop and report why it failed.
 +
 +So that can save you some time if you're struggling with an issue. Another thing that is useful to know is that all of these PHPUnit tasks, accept the ''-Dphpunit_extra_params'' switch. And if you specify the full path to a unit test file, then it will only run that one test. If you specify the path to a directory, it will only run the tests in that directory. So again, if you're trying to test something specific, you don't have to sit through the entire 15 minute test suite to wait for that test to run. You can get there immediately. Once I show you how to write tests, I'll show you how these are structured, how to find the tests you need, and so forth, since we're short on time, I won't do that right now.
 +
 +So the last thing to show you is that when we're all done, we can run ''phing.sh shutdown''. And this is going to actually just delete all of the test data and all of the configurations and shut everything down. And now our entire test environment is gone. So when we're done, if we don't want to be taking up the system resources running all those things again, this will take care of it. There's one important thing as a last little detail that I want to show you, which is that the shutdown task actually deletes all of your composer dependencies, along with everything else, which means that it has deleted Phing. That means that now if I try to start the system up again, it's not going to work because it can't find thing anymore. So I'm going to add a little bit more intelligence to my ''phing.sh'' script in my home directory to solve this problem. I'm going to assume that you have composer installed globally on your system, which in this instance I do. But if I just add before my thing command, ''if [ ! -e $VUFIND_HOME/vendor ]''. In other words, if the vendor directory in my $VUFIND_HOME directory does not exist, ''then cd $VUFIND_HOME'' ''composer install'' ''fi''. So this little check in our script will find out if you haven't installed your composer dependencies yet, which you need to do for thing to work, it will automatically reinstall them for you.
 +
 +// Complete ~/phing.sh: //
 +
 +<code bash>
 +#!/bin/bash
 +source /home/dkatz/testenv.sh
 +if [ ! -e $VUFIND_HOME/vendor ]
 +then
 +    cd $VUFIND_HOME
 +    composer install
 +fi
 +$VUFIND_HOME/vendor/bin/phing -Dapacheconfdir="/etc/apache2/conf-enabled" -Dapachectl="sudo /etc/init.d/apache2" -Dmysqlrootpass=tutorial -Dvufindurl=http://localhost/vufind_test -Dmink_driver=chrome $*</code>
 +
 +So now if I say ''phing.sh startup'' again. It's going to automatically reinstall my dependencies for me, and then it will start up the system again.
 +
 +That's everything I wanted to show you this month, hopefully you now see how you can set up an environment for testing VuFind. You've learned a little bit more about disposing of that environment when you're done. And maybe you've also learned a little bit more about style checking tools along the way. If you have any questions by all means, let me know I'm happy to answer them. So thanks again, and I look forward to next month when we can talk about actually writing some brand new tests. Thank you.
 +
 +// This is an edited version of an automated transcript. Apologies for any errors. //
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
videos/testing_1.1620404397.txt.gz · Last modified: 2021/05/07 16:19 by demiankatz