Resolves #248 - Enables and configures GitHub actions

.github/workflows/dotnetCi.yml

@@ -0,0 +1,192 @@
+name: .NET CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+
+  # Summary:
+  #
+  # * Installs and configures the environment
+  # * Builds the solution with SonarScanner analysis
+  #   * In Debug configuration
+  # * Runs all .NET and JS tests
+  #   * In Debug configuration (.NET tests)
+  #   * Producing code coverage reports, consumed by SonarScanner
+  #   * WebDriver-based tests use a locally-running Chrome browser ONLY
+  # * Packages test results as build artifacts
+  # * Builds & packs the solution in Release configuration
+  # * Uploads the Release config packages as build artifacts
+
+  build_test_and_pack:
+    name: Build, test & package
+    runs-on: ubuntu-slim
+
+    env:
+      RunNumber: ${{ github.run_number }}.${{ github.run_attempt }}
+      VersionSuffix: ci.${{ github.run_number }}
+      SonarCloudProject: csf-dev_CSF.Screenplay
+      SonarCloudUsername: craigfowler-github
+      SonarCloudUrl: https://sonarcloud.io
+      Configuration: Debug
+      Tfm: net8.0
+      DotnetVersion: 8.0.x
+      SonarCloudSecretKey: ${{ secrets.SONARCLOUDKEY }}
+      BranchName: ${{ github.event_name == 'pull_request' && github.base_ref || github.ref_name }}
+      BranchParam: ${{ github.event_name == 'pull_request' && 'sonar.pullrequest.branch' || 'sonar.branch.name' }}
+      PullRequestParam: ${{ github.event_name == 'pull_request' && format('/d:sonar.pullrequest.key={0}', github.event.number) || '' }}
+      DISPLAY: :99
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    # Install build dependencies
+
+    - name: Add .NET global tools location to PATH
+      run: echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"
+    - name: Install .NET
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: ${{ env.DotnetVersion }}
+    - name: Install SonarScanner
+      run: dotnet tool install --global dotnet-sonarscanner
+    - name: Install Coverlet console
+      run: dotnet tool install --global coverlet.console
+    - name: Install DocFX
+      run: dotnet tool install --global docfx
+    - name: Install Node.js for building JSON-to-HTML report converter
+      uses: actions/setup-node@v6.2.0
+    - name: Install Java JDK for SonarScanner
+      uses: actions/setup-java@v5.1.0
+      with:
+        java-version: 21
+        distribution: 'zulu'
+    - name: Install GUI packages so Chrome may run
+      run: |
+        sudo apt-get update
+        sudo apt install -y xorg xvfb gtk2-engines-pixbuf dbus-x11 xfonts-base xfonts-100dpi xfonts-75dpi xfonts-cyrillic xfonts-scalable psmisc
+
+    # Environment setup pre-build
+
+    - name: Setup Selenium Manager config
+      run: |
+        mkdir ~/.cache/selenium
+        cp Tools/se-config.toml ~/.cache/selenium
+    - name: Start an Xvfb display so Chrome may run
+      run: Xvfb -ac $DISPLAY -screen 0 1280x1024x16 &
+    - name: Restore .NET packages
+      run: dotnet restore
+    - name: Restore Node modules
+      run: |
+        cd CSF.Screenplay.JsonToHtmlReport.Template/src
+        npm ci
+        cd ../..
+
+    # Build and test the solution
+
+    - name: Start SonarScanner
+      run: >
+        dotnet sonarscanner begin
+        /k:${{ env.SonarCloudProject }}
+        /v:GitHub_build_${{ env.RunNumber }}
+        /o:${{ env.SonarCloudUsername }}
+        /d:sonar.host.url=${{ env.SonarCloudUrl }}
+        /d:sonar.token=${{ env.SonarCloudSecretKey }}
+        /d:${{ env.BranchParam }}=${{ env.BranchName }} ${{ env.PullRequestParam }}
+        /d:sonar.javascript.lcov.reportPaths=CSF.Screenplay.JsonToHtmlReport.Template/src/TestResults/lcov.info
+        /s:$PWD/.sonarqube-analysisproperties.xml
+    - name: Build the solution
+      run: dotnet build -c ${{ env.Configuration }} --no-incremental
+    - name: Run .NET tests with coverage
+      id: dotnet_tests
+      continue-on-error: true
+      run: |
+        for proj in Tests/*.Tests
+        do
+          projNameArray=(${proj//// })
+          projName=${projNameArray[1]}
+          assemblyPath=$proj/bin/$Configuration/$Tfm/$projName.dll
+          coverlet "$assemblyPath" --target "dotnet" --targetargs "test $proj -c $Configuration --no-build --logger:nunit --test-adapter-path:." -f=opencover -o="TestResults/$projName.opencover.xml"
+          if [ $? -ne 0 ]
+          then
+            echo "failures=true" >> $GITHUB_OUTPUT
+          fi
+        done
+    - name: Run JavaScript tests with coverage
+      id: js_tests
+      continue-on-error: true
+      run: |
+        cd CSF.Screenplay.JsonToHtmlReport.Template/src
+        npm test
+        if [ $? -ne 0 ]
+        then
+          echo "failures=true" >> $GITHUB_OUTPUT
+        fi
+        cd ../..
+
+    # Post-test tasks (artifacts, overall status)
+
+    - name: Stop SonarScanner
+      run:
+        dotnet sonarscanner end /d:sonar.token=${{ env.SonarCloudSecretKey }}
+    - name: Gracefully stop Xvfb
+      run: killall Xvfb
+      continue-on-error: true
+    - name: Upload test results artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: NUnit test results
+        path: Tests/*.Tests/**/TestResults.xml
+    - name: Upload Screenplay JSON report artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: Screenplay JSON reports
+        path: Tests/**/ScreenplayReport_*.json
+    - name: Convert Screenplay reports to HTML
+      continue-on-error: true
+      run: |
+        for report in $(find Tests/ -type f -name "ScreenplayReport_*.json")
+        do
+          reportDir=$(dirname "$report")
+          outputFile="$reportDir/ScreenplayReport.html"
+          dotnet run --no-build --framework $Tfm --project CSF.Screenplay.JsonToHtmlReport --ReportPath "$report" --OutputPath "$outputFile"
+        done
+    - name: Upload Screenplay HTML report artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: Screenplay HTML reports
+        path: Tests/**/ScreenplayReport.html
+    - name: Fail the build if any test failures
+      if: ${{ steps.dotnet_tests.outputs.failures == 'true' || steps.js_tests.outputs.failures == 'true' }}
+      run: |
+        echo "Failing the build due to test failures"
+        exit 1
+
+    # Build the apps in release mode and publish artifacts
+
+    - name: Clean the solution ahead of building in release config
+      run: dotnet clean
+    - name: Build, in release configuration
+      run: dotnet pack -p:VersionSuffix=$VersionSuffix -o packages
+    - name: Upload build result artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: Build results (NuGet)
+        path: packages/*.nupkg
+    - name: Build docs website
+      run: dotnet build -c Docs
+    - name: Upload docs website artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: Docs website
+        path: docs/**/*
+
+  # publishDocs:
+    # TODO: Take the docco site artifact and publish it to master
+
+  # runBrowserTests:
+    # TODO: Use build-results artifacts and run tests on matrix of browsers

.github/workflows/publishDocsWebsite.yml

@@ -0,0 +1,46 @@
+name: Update docs website
+
+on:
+  push:
+    branches: [ "master" ]
+
+jobs:
+
+  # This job builds the documentation website
+  # and the commits that to the master branch,
+  # which will result in replacing the currently published site
+
+  build_and_commit:
+    name: Build & commit docs website
+    runs-on: ubuntu-slim
+
+    env:
+      DotnetVersion: 8.0.x
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Add .NET global tools location to PATH
+      run: echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"
+    - name: Install .NET
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: ${{ env.DotnetVersion }}
+    - name: Install DocFX
+      run: dotnet tool install --global docfx
+    - name: Remove old docs
+      run: dotnet clean CSF.Screenplay.Docs
+    - name: Build new docs
+      run: dotnet build -c Docs CSF.Screenplay.Docs
+    - name: Add & Commit
+      uses: EndBug/add-and-commit@v9.1.4
+      with:
+        add: -A docs/
+        default_author: github_actor
+        committer_name: Github Actions Workflow (bot)
+        committer_email: github-actions-workflow@bots.noreply.github.com
+        fetch: true
+        message: Publish updated documentation website
+        push: origin master --force
+
+

.gitignore

@@ -10,3 +10,4 @@ node_modules/
 **/ScreenplayReport*
 **/TestResult.xml
 .obsidian/
+packages/

.vscode/extensions.json

@@ -4,6 +4,7 @@
         "ms-dotnettools.csdevkit",
         "bierner.markdown-mermaid",
         "davidanson.vscode-markdownlint",
-        "bpruitt-goddard.mermaid-markdown-syntax-highlighting"
+        "bpruitt-goddard.mermaid-markdown-syntax-highlighting",
+        "github.vscode-github-actions"
     ]
 }

.vscode/tasks.json

@@ -11,6 +11,33 @@
 			"problemMatcher": [],
 			"label": "dotnet: build"
 		},
+		{
+			"group": {
+				"kind": "build"
+			},
+			"command": "dotnet",
+			"args": ["build", "-p:TargetFrameworks=net8.0"],
+			"problemMatcher": [],
+			"label": "dotnet: build (net8.0 only)"
+		},
+		{
+			"group": {
+				"kind": "build"
+			},
+			"command": "dotnet",
+			"args": ["pack", "-o", "packages"],
+			"problemMatcher": [],
+			"label": "dotnet: pack"
+		},
+		{
+			"group": {
+				"kind": "none"
+			},
+			"command": "dotnet",
+			"args": ["clean"],
+			"problemMatcher": [],
+			"label": "dotnet: clean"
+		},
 		{
 			"group": {
 				"kind": "test",
@@ -21,6 +48,16 @@
 			"problemMatcher": [],
 			"label": "dotnet: test"
 		},
+		{
+			"group": {
+				"kind": "test",
+				"isDefault": true
+			},
+			"command": "dotnet",
+			"args": ["test", "-p:TargetFramework=net8.0"],
+			"problemMatcher": [],
+			"label": "dotnet: test (net8.0 only)"
+		},
 		{
 			"group": {
 				"kind": "test"