438 ftr add xqunit tests (#446)

## Description, Context and related Issue

This PR introduces XQSuite unit tests to the Edirom Online. 
I already added the test suite to the ant build script as well as the
Github actions so these tests can be run manually and automatically at
every PR.


<!--- This project only accepts pull requests related to open issues.
Please link to the issue here: -->
Refs #438 


## Types of changes
<!--- What types of changes does your code introduce? Please delete
options that are not relevant. -->
- [x] New feature (non-breaking change which adds functionality)

## Checklist
<!--- Go over all the following points, and delete options that are not
relevant. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
- [x] I have read the
[CONTRIBUTING](https://github.com/Edirom/Edirom-Online/blob/develop/CONTRIBUTING.md)
document.

.github/workflows/pre-release.yml

@@ -1,4 +1,4 @@
-name: pre-release
+name: Build, test, and tag
 
 on:
   push:
@@ -10,9 +10,6 @@ on:
 permissions:
   contents: read
 
-env:
-  DOCKER_IMAGE: bwbohl/sencha-cmd
-
 jobs:
 
   build:
@@ -22,13 +19,13 @@ jobs:
       contents: write
 
     steps:
-    - name: Chekout repository
-      uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4.2.0
+    - name: Checkout repository
+      uses: actions/checkout@v4
       with:
         submodules: 'recursive'
 
     - name: Get short sha
-      uses: benjlevesque/short-sha@599815c8ee942a9616c92bcfb4f947a3b670ab0b # v3.0
+      uses: benjlevesque/[email protected]
       id: short-sha
       with:
         length: 7       
@@ -38,7 +35,7 @@ jobs:
 
     - name: Upload Artifacts to action run
       if: github.repository == 'Edirom/Edirom-Online'
-      uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+      uses: actions/upload-artifact@v4
       with:
         # The name that the artifact will be made available under
         name: EdiromOnline_${{ steps.short-sha.outputs.sha }}.zip
@@ -47,20 +44,71 @@ jobs:
         if-no-files-found: warn # 'warn' or 'ignore' are also available, defaults to `warn` 
         #optional retention-days: 1 to 90
 
+    outputs:
+      # saving this as output for following jobs to pick up
+      artifact_name: EdiromOnline_${{ steps.short-sha.outputs.sha }}.zip
+
+
+  xqunit:
+    name: Run XQSuite unit tests
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Install libxml2-utils for xmllint
+      run: |
+        sudo apt-get update
+        sudo apt-get install libxml2-utils
+    - name: Download artifact from previous job
+      uses: actions/download-artifact@v4
+      with:
+        name: ${{ needs.build.outputs.artifact_name }}
+        path: xars
+    - name: debug
+      run: ls -laR ${{ github.workspace }}
+    - name: Create Docker container
+      run: |
+        docker create --rm --name edirom-online -p 8080:8080 stadlerpeter/existdb:6
+        for i in xars/*.xar ; do docker cp $i edirom-online:/opt/exist/autodeploy/ ; done
+    - name: Run Docker container
+      run: |
+        docker start edirom-online
+        i=0 ; while (! docker inspect edirom-online | grep -e Status....healthy) ; do if ((i > 30)) ; then echo ' **** timeout ... aborting **** ' ; exit 1 ; else sleep 5 ; echo waiting for container ... ; i=$((i+1)) ; fi ; done
+    - name: Run test suite
+      run: ant xqunit-tests
+    - name: Tear down Docker
+      run: docker kill edirom-online
+
+
+  update-tag:
+    name: Update git development tag and Github release
+    needs: [build,xqunit]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
     - name: Delete dev-release
       if: ${{ github.event_name == 'push' && github.ref_name == 'develop' }}
-      uses: dev-drprasad/[email protected]
+      run: gh release delete dev --cleanup-tag -y
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        REPO: ${{ github.event.repository.name }}
+
+    - name: Download artifact from previous job
+      uses: actions/download-artifact@v4
       with:
-        delete_release: true
-        tag_name: dev
-        github_token: ${{ secrets.GITHUB_TOKEN }}
+        name: ${{ needs.build.outputs.artifact_name }}
+        path: xars
 
     - name: Create dev-release
       if: ${{ github.event_name == 'push' && github.ref_name == 'develop' }}
       uses: ncipollo/[email protected]
       with:
         allowUpdates: true
-        artifacts: ${{ github.workspace }}/build-xar/Edirom-Online-*.xar
+        artifacts: ${{ github.workspace }}/xars/Edirom-Online-*.xar
         commit: ${{ github.sha }}
         name: "Development Build"
         prerelease: true

build.xml

@@ -2,6 +2,7 @@
 <project name="EdiromOnline" default="xar">
 
     <import file="${basedir}/.sencha/app/build-impl.xml"/>
+    <import file="${basedir}/testing/ant-tests.xml"/>
 
     <property name="project.version" value="1.0.0-beta.6"/>
     <property name="project.app" value="Edirom-Online"/>
@@ -33,6 +34,9 @@
                 <include name="help/**"/>
                 <include name="index/**"/>
             </fileset>
+            <fileset dir="${basedir}">
+                <include name="testing/**"/>
+            </fileset>
             <filterset begintoken="@" endtoken="@">
                 <filter token="project.version" value="${project.version}"/>
                 <filter token="project.app" value="${project.app}"/>

testing/XQSuite/eutil-tests.xqm

@@ -0,0 +1,40 @@
+xquery version "3.1";
+
+module namespace eut = "http://www.edirom.de/xquery/xqsuite/eutil-tests";
+
+import module namespace eutil = "http://www.edirom.de/xquery/util" at "xmldb:exist:///db/apps/Edirom-Online/data/xqm/util.xqm";
+
+declare namespace mei="http://www.music-encoding.org/ns/mei";
+declare namespace tei="http://www.tei-c.org/ns/1.0";
+declare namespace test="http://exist-db.org/xquery/xqsuite";
+declare namespace xhtml="http://www.w3.org/1999/xhtml";
+
+
+declare 
+    %test:args("<title xmlns='http://www.tei-c.org/ns/1.0' 
+        type='main'>Some Title</title>")            %test:assertEquals("tei")
+    %test:args("<render xmlns='http://www.music-encoding.org/ns/mei' 
+        xmlns:mei='http://www.music-encoding.org/ns/mei'><mei:render>
+        nested</mei:render> render</render>")       %test:assertEquals("mei")
+    %test:args("<xhtml:span xmlns:xhtml='http://www.w3.org/1999/xhtml' 
+        class='author'>Johann Evangelist Engl</xhtml:span>")     %test:assertEquals("unknown")
+    function eut:test-getNamespace($node as element()) as xs:string {
+        eutil:getNamespace($node)
+};
+
+declare 
+    %test:args("<titleStmt xmlns='http://www.tei-c.org/ns/1.0'><?prüfen?><title type='abbreviated'>
+        <identifier>P1-PA<rend rend='sup'>1</rend></identifier> – Autographe Partitur</title>
+        <title type='main'>Autographe Partitur</title>
+        <title type='sub'>Manifestation</title></titleStmt>", 
+        "de")       %test:assertEquals("unknown") %test:pending("Ticket https://github.com/Edirom/Edirom-Online/issues/103")
+    %test:args("<titleStmt xmlns='http://www.tei-c.org/ns/1.0'>
+        <title type='main'>Autographe Partitur</title>
+        <title type='sub'>Manifestation</title></titleStmt>", 
+        "de")       %test:assertEquals("Autographe Partitur")
+    %test:args("<titleStmt xmlns='http://www.tei-c.org/ns/1.0'>
+        <title type='main'>Autographe Partitur</title></titleStmt>", 
+        "de")       %test:assertEquals("Autographe Partitur")
+    function eut:test-getLocalizedTitle($node as element(), $lang as xs:string?) as xs:string {
+        eutil:getLocalizedTitle($node, $lang)
+};

testing/XQSuite/run-unit-tests.xq

@@ -0,0 +1,16 @@
+xquery version "3.1";
+
+(:~
+ : Main executable XQuery for running XQSuite unit tests
+ : @see http://exist-db.org/exist/apps/doc/xqsuite.xml
+:)
+
+(: the following line must be added to each of the modules that include unit tests :)
+import module namespace test="http://exist-db.org/xquery/xqsuite" at "resource:org/exist/xquery/lib/xqsuite/xqsuite.xql";
+
+import module namespace eut="http://www.edirom.de/xquery/xqsuite/eutil-tests" at "eutil-tests.xqm";
+
+(: the test:suite() function will run all the test-annotated functions in the module whose namespace URI you provide :)
+test:suite((
+    util:list-functions("http://www.edirom.de/xquery/xqsuite/eutil-tests")
+))

testing/ant-tests.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project basedir=".." name="EdiromOnlineTesting">
+
+    <property name="xqunit-url" value="http://localhost:8080/exist/apps/Edirom-Online/testing/XQSuite/run-unit-tests.xq"/>
+
+    <target name="run-all-tests" depends="xqunit-tests"/>
+
+    <target name="-check-dependencies">
+        <description>Check for necessary executables</description>
+        <property environment="env" /> 
+        <available file="xmllint"  
+            filepath="${env.PATH}"  
+            property="xmllint.present"/>
+        <fail unless="${xmllint.present}" 
+            message="Missing executable 'xmllint'"/>
+    </target>
+
+    <target name="xqunit-tests" depends="-check-dependencies" if="xmllint.present">
+        <description>Run the XQSuite unit tests. 
+            For general information about XQSuite see http://exist-db.org/exist/apps/doc/xqsuite.xml
+        </description>
+
+        <!--
+            Hard coded here which should actually be a dependency. 
+            Yet, the current setup needs sencha for creating this 
+            so I simply put it here, too 
+        -->
+        <mkdir dir="${temp.dir}"/>
+
+        <!-- Retrieve the unit tests from the eXistdb -->
+        <get src="${xqunit-url}" dest="${temp.dir}/xqunit-tests-results.xml"/>
+
+        <!-- Parse the results and check for errors -->
+        <exec executable="xmllint" dir="${temp.dir}" outputproperty="error.count">
+            <arg line="--xpath &quot;count(//testcase[failure])&quot; xqunit-tests-results.xml"/>
+        </exec>
+
+        <!-- Load the results and output to the logs -->
+        <loadfile srcFile="${temp.dir}/xqunit-tests-results.xml" property="xqunit-tests-results"/>
+        <echo>${xqunit-tests-results}</echo>
+
+        <!-- Fail the build if errors are encountered -->
+        <fail message="XQSuite unit tests encountered erros">
+            <condition>
+                <not>
+                    <equals arg1="${error.count}" arg2="0"/>
+                </not>
+            </condition>
+        </fail>
+    </target>
+
+</project>