[Observability] Replace basic-license annotations FTR test with unit coverage !! (elastic#270174)

## Summary

The `observability_api_integration/basic` FTR config existed solely to
assert that `POST /api/observability/annotation` returns `403` on a
basic license. That single behavior is now covered directly at
`create_annotations_client.ts`'s `ensureGoldLicense` guard via unit
tests, removing the need for a dedicated FTR config (and the associated
basic-license ES boot) just to exercise one branch.

Part of elastic#263519.

### Changes

- **Added**
`x-pack/solutions/observability/plugins/observability/server/lib/annotations/create_annotations_client.test.ts`
covering:
- The `ensureGoldLicense` guard for every gated method (`create`,
`update`, `getById`, `find`, `delete`) with both an absent license and a
license below gold. Each asserts the exact `Boom.forbidden('Annotations
require at least a gold license or a trial license.')` shape the route
handler relies on.
- The `permissions` endpoint's `hasGoldLicense` reporting under absent /
below-gold / gold-or-higher licenses.
- **Removed**
`x-pack/solutions/observability/test/observability_api_integration/basic/`
(config + `tests/index.ts` + `tests/annotations.ts`).
- **Removed** the entry from
`.buildkite/ftr-manifests/ftr_oblt_stateful_configs.yml`.
- **Updated** the plugin README to reflect the new layout (the
basic-license section is gone; trial remains).

### Why unit tests instead of a Scout port

The FTR test was an integration test for a one-line license check.
Reproducing it on Scout would require either a brand-new `kbn-scout`
server config set that boots ES with `license: 'basic'` (just to flip a
single line of behavior), or runtime license mutation against a shared
Scout server. Both are heavier than the coverage they buy. Unit coverage
at the client level exercises the same guard and is also net-new — there
were no existing unit tests for this module.

## Test plan

- [x] `node scripts/jest
x-pack/solutions/observability/plugins/observability/server/lib/annotations/create_annotations_client.test.ts`
— 14/14 passing locally.
- [x] `node scripts/eslint --fix
x-pack/solutions/observability/plugins/observability/server/lib/annotations/create_annotations_client.test.ts`
— clean.
- [ ] `node scripts/type_check --project
x-pack/solutions/observability/plugins/observability/tsconfig.json` —
running locally; will confirm in CI as well.
- [ ] CI green.

Made with [Cursor](https://cursor.com)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 2 people

.buildkite/ftr-manifests/ftr_oblt_stateful_configs.yml

@@ -28,7 +28,6 @@ enabled:
   - x-pack/solutions/observability/test/apm_api_integration/rules/config.ts
   - x-pack/solutions/observability/test/apm_api_integration/trial/config.ts
   - x-pack/solutions/observability/test/functional/apps/dataset_quality/config.ts
-  - x-pack/solutions/observability/test/observability_api_integration/basic/config.ts
   - x-pack/solutions/observability/test/observability_api_integration/trial/config.ts
   - x-pack/solutions/observability/test/observability_functional/with_rac_write.config.ts
   - x-pack/solutions/observability/test/observability_ai_assistant_functional/enterprise/config.ts

x-pack/solutions/observability/plugins/observability/README.md

@@ -47,24 +47,7 @@ open target/coverage/jest/index.html
 
 ## API integration testing
 
-API tests are separated in two suites:
-
-- a basic license test suite
-- a trial license test suite (the equivalent of gold+)
-
-This requires separate test servers and test runners.
-
-### Basic
-
-```
-# Start server
-node scripts/functional_tests_server --config x-pack/solutions/observability/test/observability_api_integration/basic/config.ts
-
-# Run tests
-node scripts/functional_test_runner --config x-pack/solutions/observability/test/observability_api_integration/basic/config.ts
-```
-
-The API tests for "basic" are located in `x-pack/solutions/observability/test/observability_api_integration/basic/tests`.
+API tests run under a trial license (the equivalent of gold+). Basic-license behavior is covered by unit tests (see `server/lib/annotations/create_annotations_client.test.ts`).
 
 ### Trial
 

x-pack/solutions/observability/plugins/observability/server/lib/annotations/create_annotations_client.test.ts

@@ -0,0 +1,183 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { elasticsearchServiceMock } from '@kbn/core/server/mocks';
+import { licensingMock } from '@kbn/licensing-plugin/server/mocks';
+import { loggerMock } from '@kbn/logging-mocks';
+import { DEFAULT_ANNOTATION_INDEX } from '../../../common/annotations';
+import { createAnnotationsClient } from './create_annotations_client';
+
+const FORBIDDEN_MESSAGE = 'Annotations require at least a gold license or a trial license.';
+
+const baseAnnotation = {
+  annotation: { type: 'deployment' },
+  '@timestamp': '2026-05-20T00:00:00.000Z',
+  message: 'test message',
+  tags: ['apm'],
+};
+
+const buildClient = ({
+  license,
+}: {
+  license?: ReturnType<typeof licensingMock.createLicenseMock>;
+} = {}) => {
+  const esClient = elasticsearchServiceMock.createElasticsearchClient();
+  const logger = loggerMock.create();
+
+  return {
+    esClient,
+    client: createAnnotationsClient({
+      index: DEFAULT_ANNOTATION_INDEX,
+      esClient,
+      logger,
+      license,
+    }),
+  };
+};
+
+const mockHasPrivileges = (
+  esClient: ReturnType<typeof elasticsearchServiceMock.createElasticsearchClient>
+) => {
+  esClient.security.hasPrivileges.mockResponse({
+    username: 'elastic',
+    has_all_requested: true,
+    cluster: {},
+    index: {
+      [DEFAULT_ANNOTATION_INDEX]: { read: true, write: true },
+    },
+    application: {},
+  });
+};
+
+describe('createAnnotationsClient', () => {
+  describe('license guard', () => {
+    // The license guard throws synchronously before the wrapped async function runs,
+    // so we await an already-resolved promise then invoke the call inside the .then,
+    // turning the sync throw into a rejection we can inspect.
+    const captureError = async (fn: () => unknown) => {
+      try {
+        await Promise.resolve().then(fn);
+      } catch (error) {
+        return error;
+      }
+      throw new Error('Expected the call to throw a forbidden error');
+    };
+
+    const expectForbidden = (error: any) => {
+      expect(error).toBeDefined();
+      expect(error.isBoom).toBe(true);
+      expect(error.output.statusCode).toBe(403);
+      expect(error.output.payload).toEqual({
+        statusCode: 403,
+        error: 'Forbidden',
+        message: FORBIDDEN_MESSAGE,
+      });
+    };
+
+    it.each(['create', 'update', 'getById', 'find', 'delete'] as const)(
+      'rejects %s with a forbidden error when the license is missing',
+      async (method) => {
+        const { client, esClient } = buildClient();
+
+        const error = await captureError(() =>
+          (client[method] as (params: unknown) => Promise<unknown>)({})
+        );
+        expectForbidden(error);
+
+        expect(esClient.index).not.toHaveBeenCalled();
+        expect(esClient.search).not.toHaveBeenCalled();
+        expect(esClient.deleteByQuery).not.toHaveBeenCalled();
+      }
+    );
+
+    it.each(['create', 'update', 'getById', 'find', 'delete'] as const)(
+      'rejects %s with a forbidden error when the license is below gold',
+      async (method) => {
+        const license = licensingMock.createLicenseMock();
+        license.hasAtLeast.mockReturnValue(false);
+
+        const { client } = buildClient({ license });
+
+        const error = await captureError(() =>
+          (client[method] as (params: unknown) => Promise<unknown>)({})
+        );
+        expectForbidden(error);
+
+        expect(license.hasAtLeast).toHaveBeenCalledWith('gold');
+      }
+    );
+
+    it('lets create proceed past the license guard when the license is gold or higher', async () => {
+      const license = licensingMock.createLicenseMock();
+      license.hasAtLeast.mockReturnValue(true);
+
+      const { client, esClient } = buildClient({ license });
+
+      esClient.index.mockResponse({
+        _id: 'annotation-1',
+        _index: DEFAULT_ANNOTATION_INDEX,
+        _shards: { total: 1, successful: 1, failed: 0 },
+        result: 'created',
+        _version: 1,
+        _seq_no: 0,
+        _primary_term: 1,
+      });
+
+      await expect(client.create(baseAnnotation)).resolves.toEqual({
+        _id: 'annotation-1',
+        _index: DEFAULT_ANNOTATION_INDEX,
+        _source: expect.objectContaining({
+          message: 'test message',
+          annotation: expect.objectContaining({ type: 'deployment', title: 'test message' }),
+        }),
+      });
+
+      expect(license.hasAtLeast).toHaveBeenCalledWith('gold');
+      expect(esClient.index).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('permissions', () => {
+    it('reports hasGoldLicense: false when the license is below gold', async () => {
+      const license = licensingMock.createLicenseMock();
+      license.hasAtLeast.mockReturnValue(false);
+
+      const { client, esClient } = buildClient({ license });
+      mockHasPrivileges(esClient);
+
+      const permissions = await client.permissions();
+
+      expect(permissions).toEqual({
+        index: DEFAULT_ANNOTATION_INDEX,
+        hasGoldLicense: false,
+        read: true,
+        write: true,
+      });
+    });
+
+    it('reports hasGoldLicense: false when no license is provided', async () => {
+      const { client, esClient } = buildClient();
+      mockHasPrivileges(esClient);
+
+      const permissions = await client.permissions();
+
+      expect(permissions.hasGoldLicense).toBe(false);
+    });
+
+    it('reports hasGoldLicense: true when the license is gold or higher', async () => {
+      const license = licensingMock.createLicenseMock();
+      license.hasAtLeast.mockReturnValue(true);
+
+      const { client, esClient } = buildClient({ license });
+      mockHasPrivileges(esClient);
+
+      const permissions = await client.permissions();
+
+      expect(permissions.hasGoldLicense).toBe(true);
+    });
+  });
+});