About Features Downloads Getting Started Documentation Events Support GitHub

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

Site Tools


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

Next revision
Previous revision
Next revisionBoth sides next revision
videos:testing_1 [2021/05/04 17:06] – created demiankatzvideos:testing_1 [2021/10/22 14:37] – [Video 16: Testing, Part 1: Setting Up a Test Environment] demiankatz
Line 1: Line 1:
 ====== Video 16: Testing, Part 1: Setting Up a Test Environment ====== ====== Video 16: Testing, Part 1: Setting Up a Test Environment ======
  
-// Details coming soon! //+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]]. 
 + 
 +===== Scripts ===== 
 + 
 +Several scripts are created during the course of this video; they are transcribed here for your convenience. 
 + 
 +==== 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> 
 + 
 +==== 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> 
 + 
 +==== phing.sh ==== 
 + 
 +<code bash> 
 +#!/bin/bash 
 + 
 +# Set environmental variables 
 +source ~/testenv.sh 
 + 
 +# Reinstall dependencies 
 +if [ ! -e $VUFIND_HOME/vendor ] 
 +then 
 +    cd $VUFIND_HOME 
 +    composer install 
 +fi 
 + 
 +# Run phing with preferred parameters 
 +$VUFIND_HOME/vendor/bin/phing -Dextra_shutdown_cleanup="sudo chown -R {USER}:{USER} $VUFIND_HOME/local/cache" -Dapacheconfdir="/etc/apache2/conf-enabled" -Dapachectl="sudo /etc/init.d/apache2" -Dmysqlrootpass={PASSWORD} -Dvufindurl=http://localhost/vufind_test -Dmink_driver=chrome $* 
 +</code> 
 + 
 +==== testenv.sh ==== 
 + 
 +<code bash> 
 +export VUFIND_HOME=/{path}/vufind 
 +export VUFIND_LOCAL=$VUFIND_HOME/local 
 +</code> 
 + 
 +===== Related Resources ===== 
 + 
 +  - [[development:recommended_tools#meeting_project_standards|Recommended Tools for Meeting Project Standards]] 
 +  - [[development:testing:unit_tests|Unit Testing Documentation]] 
 + 
 +===== 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 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'
 +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'
 +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'
 +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'
 +have to do this step because there'
 +nothing there to stop 
 +i'm just doing that so my demo doesn'
 +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'
 +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 
 ---- struct data ---- ---- struct data ----
 ---- ----
  
videos/testing_1.txt · Last modified: 2023/05/09 20:58 by crhallberg