Deprecate FunctionalTestBase (#9140)

## What changed?

1. add lint rule to not use FunctionalTestBase for new functional tests.
2. basic documentation for new `TestEnv` alternative approach

## Why?

Enforce policy for new tests while migrating existing ones.

## How did you test it?
- [ ] built
- [ ] run locally and tested manually
- [x] covered by existing tests
- [ ] added new unit test(s)
- [ ] added new functional test(s)

.github/.golangci.yml

@@ -38,12 +38,14 @@ linters:
           msg: "Please avoid using panic in application code"
         - pattern: time\.Now
           msg: "Using time.Now is not allowed in chasm/lib package (non-test files), use ctx.Now(component) instead"
-        - pattern: '^Unix$'
+        - pattern: "^Unix$"
           msg: "Do not use .Unix() for Cassandra timestamps (returns seconds). Use p.UnixMilliseconds() which returns milliseconds."
-        - pattern: '^UnixMilli$'
+        - pattern: "^UnixMilli$"
           msg: "Do not use .UnixMilli() for Cassandra timestamps. Use p.UnixMilliseconds() for consistency and proper zero-time handling."
-        - pattern: '^UnixNano$'
+        - pattern: "^UnixNano$"
           msg: "Do not use .UnixNano() for Cassandra timestamps. Use p.UnixMilliseconds() which returns milliseconds."
+        - pattern: FunctionalTestBase
+          msg: "FunctionalTestBase is deprecated. Use testcore.NewEnv(t) instead. See docs/development/testing.md for details."
     depguard:
       rules:
         main:
@@ -185,6 +187,10 @@ linters:
         text: "panic"
         linters:
           - forbidigo
+      - path: tests/testcore/.*\.go$ # still needed in tests/testcore/ until we remove testify suites entirely
+        text: "FunctionalTestBase"
+        linters:
+          - forbidigo
       - path: _test\.go|tests/.+\.go|common/testing/
         text: "(cyclomatic|cognitive)" # false positives when using subtests
         linters:

docs/development/testing.md

@@ -16,6 +16,7 @@ This document describes the project's testing setup, utilities and best practice
 - `TEMPORAL_TEST_OTEL_OUTPUT`: Enables OpenTelemetry (OTEL) trace output for failed tests to the provided file path.
 - `TEMPORAL_TEST_SHARED_CLUSTERS`: Number of shared clusters in the pool. Each can be used by multiple tests simultaneously.
 - `TEMPORAL_TEST_DEDICATED_CLUSTERS`: Number of dedicated clusters in the pool. Each can be used by one test only at a time.
+
 ### Debugging via IDE
 
 #### GoLand
@@ -117,6 +118,22 @@ It is *not* a substitute for regular error handling, validation, or control flow
 In functional tests, a failed soft assertion will not stop the test execution immediately, but it
 will ultimately fail the test.
 
+### Test Cluster
+
+Use `testcore.NewEnv(t)` to create a test environment with access to a Temporal cluster for end-to-end testing.
+
+```go
+func TestMyFeatureSuite(t *testing.T) {
+    t.Run("scenario one", func(t *testing.T) {
+        s := testcore.NewEnv(t)
+        // ...
+    })}
+```
+
+Note that each test has its own namespace (`s.Namespace()`) for isolation.
+
+> **Note:** The legacy `FunctionalTestBase` (using testify's `suite`) has been deprecated for new tests.
+
 ## OpenTelemetry (OTEL)
 
 To debug your test by analysing observability traces, set the following environment variables: