docs: Update agent development and integration testing documentation (#3063)

* WIP

* Fix profiler build and local testing documentation

Also fix issue with linux profiler build docker-compose file where it would bomb out if a certain env var wasn't set, for a debug version of the profiler that isn't really relevant most of the time.

* Update docs/integration-tests.md

Co-authored-by: Marty T <[email protected]>

* Add a note for extra clarity

---------

Co-authored-by: Marty T <[email protected]>
Co-authored-by: Chris Ventura <[email protected]>

Author: 3 people

docs/development.md

@@ -1,15 +1,15 @@
 # Development
 
 ## Requirements
-* [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
+* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)
   * Workloads
     * .NET desktop development
     * Desktop development with C++
   * Individual components
     * C++ ATL for v142 build tools (x86 & x64)
 * Optional installs:
-  * [Docker Desktop for Windows](https://hub.docker.com/editions/community/docker-ce-desktop-windows/) for building the native Linux binaries.
-  * [WiX Toolset 3.11](https://wixtoolset.org/releases/) and the WiX Toolset Visual Studio 2019 Extension for building the Windows MSI installer.
+  * [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) for building the native Linux binaries, as well as running containerized integration tests.
+  * [HeatWave](https://www.firegiant.com/heatwave/) is a Visual Studio extension that enables building the [agent MSI installer solution](../src/Agent/MsiInstaller/MsiInstaller.sln).
 
 ## Building
 
@@ -26,6 +26,7 @@ To get started quickly, this is the only solution you need to build. Building th
 | .NET Core | Windows | x64 | src/Agent/newrelichome_x64_coreclr |
 | .NET Core | Windows | x86 | src/Agent/newrelichome_x86_coreclr |
 | .NET Core | Linux | x64 | src/Agent/newrelichome_x64_coreclr_linux |
+| .NET Core | Linux | arm64 | src/Agent/newrelichome_arm64_coreclr_linux |
 
 These home directories can be used to run and test the agent in your development environment.
 
@@ -51,9 +52,9 @@ CORECLR_PROFILER_PATH=path\to\home\directory\NewRelic.Profiler.dll
 
 ### Profiler.sln
 
-The Profiler.sln builds the native profiler component of the .NET agent. The profiler implements interfaces defined by the unmanaged [.NET Profiling API](https://docs.microsoft.com/en-us/dotnet/framework/unmanaged-api/profiling/) that enable the agent to attach to and monitor a .NET process.
+The Profiler.sln builds the native profiler component of the .NET agent. The profiler implements interfaces defined by the unmanaged [.NET Profiling API](https://docs.microsoft.com/en-us/dotnet/framework/unmanaged-api/profiling/) that enable the agent to attach to and monitor a .NET process.  See [the profiler README](../src/Agent/NewRelic/Profiler/README.md) for more details.
 
-As mentioned above, this solution does not need to be built if you will only be working with the agent's managed C# code. Pre-built versions of the profiler for both Windows (x86 and x64) and Linux (x64) are checked into the repository (src/Agent/_profilerBuild) and are used for creating the home directories built by the FullAgent.sln. These pre-built versions are for development purposes only, and should be updated if you do work on the profiler.
+As mentioned above, this solution does not need to be built if you will only be working with the agent's managed C# code. The profiler is [available as a NuGet package](https://www.nuget.org/packages/NewRelic.Agent.Internal.Profiler) and is referenced by the full agent solution from NuGet [here](https://github.com/newrelic/newrelic-dotnet-agent/blob/1f446c282811a0f2ccd71a088b35397a29d961a0/src/Agent/NewRelic/Home/Home.csproj#L16).  
 
 You can use a Powershell [script](../src/Agent/NewRelic/Profiler/build/build.ps1) to build the profiler.
 
@@ -78,6 +79,23 @@ build.ps1 -Platform linux
 build.ps1
 ```
 
+#### Local profiler testing
+
+In order to integrate local profiler changes with local builds of the FullAgent solution:
+
+1. First, build the FullAgent solution from Visual Studio (creating the various agent home dirs in `src/Agent`).
+2. Build the profiler for all platforms and architectures: `build.ps1` (which places the profiler artifacts in `src/Agent/_profilerBuild`)
+3. Copy the relevant profiler .dll (Windows) or .so (Linux) to the appropriate agent home folder on your system, overwriting the version pulled from NuGet:
+```
+# Example shown for the Windows 64-bit profiler, testing with the Windows CoreCLR (.NET Core/.NET) version of the agent
+copy C:\workspace\newrelic-dotnet-agent\src\Agent\_profilerBuild\x64-Release\NewRelic.Profiler.dll C:\workspace\newrelic-dotnet-agent\src\Agent\newrelichome_x64_coreclr\
+
+# Example shown for the Linux profiler and Linux
+copy C:\workspace\newrelic-dotnet-agent\src\Agent\_profilerBuild\linux-x64-release\libNewRelicProfiler.so C:\workspace\newrelic-dotnet-agent\src\Agent\newrelichome_x64_coreclr_linux\
+```
+
+Note that if you rebuild the agent solution after copying locally-build profiler files to the agent home dirs, the profiler files will be overwritten with the NuGet package version, and you'll need to copy the local profile files to the home dirs again. 
+
 ## Testing
 
 * Unit tests use the NUnit framework and are contained in the solutions. Run them using the Visual Studio Test Explorer.

docs/integration-tests.md

@@ -8,9 +8,9 @@ These tests execute against valid New Relic accounts and test a variety of featu
 
 ## Testing on Windows with Visual Studio
 
-Visual Studio 2022 or greater preferred.
+Visual Studio 2022 or greater required.
 
-Visual Studio 2019 may work with .NET 6 additionally installed.
+All generally available and supported .NET runtimes should be installed (e.g. .NET 8 and .NET 9 as of March 2025)
 
 ### Additional install requirements
 
@@ -22,8 +22,8 @@ Install the "ASP.NET and web development" workload in the "Web & Cloud" category
 
 Depending on which version of Visual Studio you are using, you may have to install some or all of the following:
 
-* .NET 6
-* .NET 7
+* .NET 8
+* .NET 9
 * .NET Framework 4.7.1 targeting pack
 * .NET Framework 4.8.0 targeting pack
 * .NET Framework 4.8.1 targeting pack
@@ -196,7 +196,7 @@ See the test secrets section above on configuring an appropriate account.
 
 #### Selenium tests
 
-We currently have one test that executes a JavaScript ajax request via Selenium. This requires Internet Explorer to be installed and does not yet work with Edge.
+We currently have one test that executes a JavaScript ajax request via Selenium. This requires Chrome to be installed.
 
 * NewRelic.Agent.IntegrationTests.BasicInstrumentation.BasicAspWebService.Test
 
@@ -226,7 +226,7 @@ For more on metric normalization rules see: https://docs.newrelic.com/docs/new-r
 
 #### W3C validation tests
 
-The W3C validation tests requiring installing Python 3.x and a dependency. See the "Python and dependencies" section above.
+The W3C validation tests requiring installing Python 3.x and a dependency (`aiohttp`). See the "Python and dependencies" section above.
 
 #### Distributed Tracing tests
 
@@ -259,20 +259,9 @@ We recommend using [WSL](https://docs.microsoft.com/en-us/windows/wsl/about) to
 
 ### Linux system setup
 
-You will need to install the .NET SDKs for .NET Core 3.1, .NET 5, .NET 6, and .NET 7.
+You will need to install the .NET SDKs for currently available and supported .NET runtimes (e.g. .NET 8 and .NET 9 as of March 2025).
 
-```
-sudo apt-get update -q -y && sudo apt-get install -q -y curl
-sudo mkdir -p /usr/share/dotnet
-
-sudo curl -sSL https://builds.dotnet.microsoft.com/dotnet/Sdk/3.1.414/dotnet-sdk-3.1.414-linux-x64.tar.gz | sudo tar -xzC /usr/share/dotnet
-sudo curl -sSL https://builds.dotnet.microsoft.com/dotnet/Sdk/5.0.401/dotnet-sdk-5.0.401-linux-x64.tar.gz | sudo tar -xzC /usr/share/dotnet
-sudo curl -sSL https://builds.dotnet.microsoft.com/dotnet/Sdk/6.0.100/dotnet-sdk-6.0.100-linux-x64.tar.gz | sudo tar -xzC /usr/share/dotnet
-sudo curl -sSL https://builds.dotnet.microsoft.com/dotnet/Sdk/7.0.100/dotnet-sdk-7.0.100-linux-x64.tar.gz | sudo tar -xzC /usr/share/dotnet
-
-sudo ln -sf /usr/share/dotnet/dotnet /usr/bin/dotnet
-dotnet --list-sdks
-```
+See Microsoft's documentation for how to install the required SDKs for your particular Linux distro and hardware platform: https://learn.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual
 
 ### Set up test secrets
 
@@ -285,12 +274,12 @@ Refer to the section above in the Windows setup instructions regarding configuri
 As previously mentioned, the agent solution needs to be built on Windows.  If you are using an Ubuntu VM in WSL, you can use this workflow to run the agent integration tests on Linux:
 
 1. Build the FullAgent.sln in Visual Studio.
-2. Copy the agent repo to the Ubuntu VM.  The VM's filesystem can be accessed from the Windows host using this path: `\\wsl$\Ubuntu-20.04` (replace `Ubuntu-20.04` with the name of your VM if it's different).
+2. Copy the agent repo to the Ubuntu VM.  The VM's filesystem can be accessed from the Windows host using this path: `\\wsl$\Ubuntu-24.04` (replace `Ubuntu-24.04` with the name of your VM if it's different).
 3. In the VM, from the shell:
 
 ```
 cd {DOTNET_AGENT_REPO_PATH}/tests/Agent/IntegrationTests/IntegrationTests
-sudo dotnet test -f netcoreapp3.1 -c Release --filter RuntimeFramework=NetCore
+sudo dotnet test -f net9.0 -c Release --filter RuntimeFramework=NetCore
 ```
 
 For more details on how to use dotnet test, see https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-test.

src/Agent/NewRelic/Profiler/docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3.4'
-
 services:
 
     build:
@@ -17,7 +15,7 @@ services:
         privileged: true
         volumes: 
             - .:/profiler
-            - $CORECLR_NEW_RELIC_HOME:/agent
+            - ${CORECLR_NEW_RELIC_HOME:-/workspace/src/Agent/NewRelic/newrelichome_x64_coreclr_linux}:/agent
         working_dir: /profiler/linux/
     build_arm64:
         platform: linux/arm64/v8