Include taskpoller in test guidelines (#6959)

## What changed?
<!-- Describe what has changed in this PR -->

Added new taskpoller to project's testing guidelines.

## Why?
<!-- Tell your future self why have you made these changes -->

To recommend this behavior to newcomers.

## How did you test it?
<!-- How have you verified this change? Tested locally? Added a unit
test? Checked in staging env? -->

## Potential risks
<!-- Assuming the worst case, what can be broken when deploying this
change to production? -->

## Documentation
<!-- Have you made sure this change doesn't falsify anything currently
stated in `docs/`? If significant
new behavior is added, have you described that in `docs/`? -->

## Is hotfix candidate?
<!-- Is this PR a hotfix candidate or does it require a notification to
be sent to the broader community? (Yes/No) -->

common/testing/taskpoller/taskpoller.go

@@ -120,10 +120,10 @@ func (p *TaskPoller) PollNexusTask(
 }
 
 // PollAndHandleWorkflowTask issues a PollWorkflowTaskQueueRequest to obtain a new workflow task,
-// invokes the handler with the task, and completes/fails the task accordingly.
+// invokes the handler with the task, and completes/fails the task accordingly. Is it a blocking call.
 // Any unspecified but required request and response fields are automatically generated using `tv`.
 // Returning an error from `handler` fails the task.
-// If no task is available, it returns NoTaskAvailable.
+// If no task is available, it returns `NoWorkflowTaskAvailable`.
 func (p *TaskPoller) PollAndHandleWorkflowTask(
 	tv *testvars.TestVars,
 	handler func(task *workflowservice.PollWorkflowTaskQueueResponse) (*workflowservice.RespondWorkflowTaskCompletedRequest, error),
@@ -135,9 +135,10 @@ func (p *TaskPoller) PollAndHandleWorkflowTask(
 }
 
 // HandleTask invokes the provided handler with the task poll result, and completes/fails the task accordingly.
+// Is it a blocking call.
 // Any unspecified but required request and response fields are automatically generated using `tv`.
 // Returning an error from `handler` fails the task.
-// If no task is available, it returns NoTaskAvailable.
+// If no task is available, it returns `NoWorkflowTaskAvailable`.
 func (p *workflowTaskPoller) HandleTask(
 	tv *testvars.TestVars,
 	handler func(task *workflowservice.PollWorkflowTaskQueueResponse) (*workflowservice.RespondWorkflowTaskCompletedRequest, error),
@@ -265,6 +266,7 @@ func (p *nexusTaskPoller) HandleTask(
 }
 
 // HandleWorkflowTask invokes the provided handler with the provided task, and completes/fails the task accordingly.
+// Is it a blocking call.
 // Any unspecified but required request and response fields are automatically generated using `tv`.
 // Returning an error from `handler` fails the task.
 func (p *TaskPoller) HandleWorkflowTask(
@@ -289,10 +291,10 @@ func (p *TaskPoller) PollActivityTask(
 }
 
 // PollAndHandleActivityTask issues a PollActivityTaskQueueRequest to obtain a new activity task,
-// invokes the handler with the task, and completes/fails the task accordingly.
+// invokes the handler with the task, and completes/fails the task accordingly. Is it a blocking call.
 // Any unspecified but required request and response fields are automatically generated using `tv`.
 // Returning an error from `handler` fails the task.
-// If no task is available, it returns NoTaskAvailable.
+// If no task is available, it returns `NoActivityTaskAvailable`.
 func (p *TaskPoller) PollAndHandleActivityTask(
 	tv *testvars.TestVars,
 	handler func(task *workflowservice.PollActivityTaskQueueResponse) (*workflowservice.RespondActivityTaskCompletedRequest, error),
@@ -304,6 +306,7 @@ func (p *TaskPoller) PollAndHandleActivityTask(
 }
 
 // HandleActivityTask invokes the provided handler with the provided task, and completes/fails the task accordingly.
+// Is it a blocking call.
 // Any unspecified but required request and response fields are automatically generated using `tv`.
 // Returning an error from `handler` fails the task.
 func (p *TaskPoller) HandleActivityTask(
@@ -321,9 +324,10 @@ func (p *TaskPoller) HandleActivityTask(
 }
 
 // HandleTask invokes the provided handler with the task poll result, and completes/fails the task accordingly.
+// Is it a blocking call.
 // Any unspecified but required request and response fields are automatically generated using `tv`.
 // Returning an error from `handler` fails the task.
-// If no task is available, it returns NoTaskAvailable.
+// If no task is available, it returns `NoActivityTaskAvailable`.
 func (p *activityTaskPoller) HandleTask(
 	tv *testvars.TestVars,
 	handler func(task *workflowservice.PollActivityTaskQueueResponse) (*workflowservice.RespondActivityTaskCompletedRequest, error),

docs/development/testing.md

@@ -6,7 +6,7 @@ This document describes the project's testing utilities and best practices.
 
 Test helpers can be found in the [common/testing](../../common/testing) package.
 
-### testvars helper
+### testvars package
 
 Instead of creating identifiers like task queue name, namespace or worker identity by hand,
 use the `testvars` package.
@@ -27,3 +27,13 @@ func TestFoo(t *testing.T) {
     }
 }
 ```
+
+### taskpoller package
+
+For end-to-end testing, consider using `taskpoller.TaskPoller` to handle workflow tasks. This is
+useful when you need full control over the worker behavior in a way that the SDK cannot provide;
+or if there's no SDK support for that API available yet.
+
+You'll find a fully initialized task poller in any functional test suite, look for `s.TaskPoller`.
+
+_NOTE: The previous `testcore.TaskPoller` has been deprecated and should not be used in new code._