Add debugging tests section (#541)

Author: Charles-Gagnon

.vscode/launch.json

@@ -13,6 +13,12 @@
             "request": "attach",
             "port": 9229,
             "preLaunchTask": "func: host start"
+        },
+        {
+            "name": "Attach to Function Host",
+            "type": "coreclr",
+            "request": "attach",
+            "processName": "func.exe"
         }
     ]
 }

samples/samples-java/.vscode/tasks.json

@@ -9,7 +9,8 @@
 			"options": {
 				"cwd": "${workspaceFolder}/target/azure-functions/samples-java-1665766173929"
 			},
-			"dependsOn": "package (functions)"
+			"dependsOn": "package (functions)",
+			"label": "func: host start"
 		},
 		{
 			"label": "package (functions)",

samples/samples-js/.vscode/tasks.json

@@ -1,17 +1,18 @@
 {
-	"version": "2.0.0",
-	"tasks": [
+    "version": "2.0.0",
+    "tasks": [
         {
             "type": "func",
             "command": "host start",
             "problemMatcher": "$func-node-watch",
             "isBackground": true,
-            "dependsOn": "npm install (functions)"
+            "dependsOn": "npm install (functions)",
+            "label": "func: host start"
         },
         {
             "type": "shell",
             "label": "npm install (functions)",
-            "command": "npm install"
+            "command": "npm install",
         },
         {
             "type": "shell",

samples/samples-outofproc/.vscode/tasks.json

@@ -63,7 +63,8 @@
 			},
 			"command": "host start",
 			"isBackground": true,
-			"problemMatcher": "$func-dotnet-watch"
+			"problemMatcher": "$func-dotnet-watch",
+			"label": "func: host start"
 		}
 	]
 }

samples/samples-powershell/.vscode/tasks.json

@@ -5,7 +5,8 @@
 			"type": "func",
 			"command": "host start",
 			"problemMatcher": "$func-powershell-watch",
-			"isBackground": true
+			"isBackground": true,
+			"label": "func: host start"
 		}
 	]
 }

samples/samples-python/.vscode/tasks.json

@@ -1,12 +1,13 @@
 {
-	"version": "2.0.0",
-	"tasks": [
+    "version": "2.0.0",
+    "tasks": [
         {
             "type": "func",
             "command": "host start",
             "problemMatcher": "$func-python-watch",
             "isBackground": true,
             "dependsOn": "pip install (functions)",
+            "label": "func: host start"
         },
         {
             "label": "pip install (functions)",

test/Integration/test-java/.vscode/tasks.json

@@ -9,7 +9,8 @@
 			"options": {
 				"cwd": "${workspaceFolder}/target/azure-functions/test-java-1666041146813"
 			},
-			"dependsOn": "package (functions)"
+			"dependsOn": "package (functions)",
+			"label": "func: host start"
 		},
 		{
 			"label": "package (functions)",

test/README.md

@@ -94,10 +94,49 @@ Our integration tests are based on functions from the samples project. To run in
         }
    ```
 
-## Troubleshooting Tests
+## Troubleshooting Test Failures
 
 This section lists some things to try to help troubleshoot test failures
 
+### Debug Integration tests
+
+You can debug tests locally by following these steps.
+
+The first part is to identify what you want to debug so you know which process to attach to. There are between 2 and 3 different processes to attach to :
+
+#### Test Runner
+
+To debug the test code itself (anything under the `test` folder) you will need to attach to the VS Test Runner that's running the tests.
+
+Visual Studio : Right click on the test in the test explorer and click "Debug"
+Visual Studio Code : Install a test explorer extension such as [.NET Core Test Explorer](https://marketplace.visualstudio.com/items?itemName=formulahendry.dotnet-test-explorer), go to the Tests panel, find the `.NET Test Explorer` view, right click the test you want to run and click "Debug Test"
+
+#### Function Host
+
+To debug either any core extension code (anything under the `src` folder) OR function code for .NET In-Process tests you will need to attach to the Function Host that's running the functions.
+
+To do this and be able to set breakpoints before the test runs you will need to follow these steps :
+
+1. Go to [IntegrationTestBase.cs](./Integration/IntegrationTestBase.cs) and in `StartFunctionHost` add a `return;` on the first line - this is to skip having the test start up the function host itself (since you'll be doing it manually)
+2. `cd` to the directory containing the functions to run - this will be in the `test/bin/Debug/net6/SqlExtensionSamples/<LANG>` folder (e.g. `test/bin/Debug/net6/SqlExtensionSamples/samples-csharp`)
+3. Run `func host start --functions <FUNCTION_NAME>` - replacing `<FUNCTION_NAME>` with the name of the function you want to debug (e.g. `func host start --functions AddProduct`)
+4. Attach to the func.exe process
+   * Visual Studio : Use `Attach to Process...`.
+   * VS Code you can use `Attach to Function Host` debug target (at the root level of the project)
+
+    **NOTE** If you don't see your breakpoints appear make sure you're using the correct version of the extension DLL. For non-.NET languages this will mean copying over the latest locally built version to the extension bundle as detailed [here](#extension-bundle). If you don't do this the host will be using a different version of the DLL that you won't have symbols for so breakpoints won't be able to load.
+5. Run your test
+
+#### Function Worker (Non .NET Isolated Functions only)
+
+For all functions that run in a worker process (which is everything other than .NET In-Process functions) if you need to debug the function code itself then you will need to use the native debugger to attach to the process. The easiest way to do that is to follow these steps:
+
+1. Open up a new instance of VS Code into the samples/test folder containing the function you want to debug (e.g. `samples/samples-powershell` or `test/Integration/test-powershell`)
+2. Modify the `.vscode/tasks.json` file for that folder and add `--functions <FUNCTION_NAME>` to the end of the command property for `func: host start`. (e.g. `"command": "host start --functions AddProduct"`)
+3. Update the `local.settings.json` in that folder and fill in the value for `SqlConnectionString` (since the test is no longer controlling the startup of the function host)
+4. Click F5 to run the `Attach to <LANG> Functions` target, this will launch the specified function and attach the debugger to it
+5. Run your test
+
 ### Enable debug logging on the Function
 
 Enabling debug logging can greatly increase the information available which can help track down issues or understand at least where the problem may be. To enable debug logging for the Function open [host.json](../samples/samples-csharp/host.json) and add the following property to the `logLevel` section, then rebuild and re-run your test.