add documentation around newly created e2e tests explaining bug and specific regression to be on the lookout for if these start failing

Author: dhurley14

x-pack/test/detection_engine_api_integration/security_and_spaces/tests/create_rules.ts

@@ -68,6 +68,25 @@ export default ({ getService }: FtrProviderContext) => {
         expect(bodyToCompare).to.eql(getSimpleRuleOutput());
       });
 
+      /*
+       This test is to ensure no future regressions introduced by the following scenario
+       a call to updateApiKey was invalidating the api key used by the
+       rule while the rule was executing, or even before it executed,
+       on the first rule run.
+       this pr https://github.com/elastic/kibana/pull/68184
+       fixed this by finding the true source of a bug that required the manual
+       api key update, and removed the call to that function.
+
+       When the api key is updated before / while the rule is executing, the alert
+       executor no longer has access to a service to update the rule status
+       saved object in Elasticsearch. Because of this, we cannot set the rule into
+       a 'failure' state, so the user ends up seeing 'going to run' as that is the
+       last status set for the rule before it erupts in an error that cannot be
+       recorded inside of the executor.
+
+       This adds an e2e test for the backend to catch that in case
+       this pops up again elsewhere.
+      */
       it('should create a single rule with a rule_id and validate it ran successfully', async () => {
         const simpleRule = getSimpleRule();
         const { body } = await supertest

x-pack/test/detection_engine_api_integration/security_and_spaces/tests/create_rules_bulk.ts

@@ -71,6 +71,25 @@ export default ({ getService }: FtrProviderContext): void => {
         expect(bodyToCompare).to.eql(getSimpleRuleOutput());
       });
 
+      /*
+       This test is to ensure no future regressions introduced by the following scenario
+       a call to updateApiKey was invalidating the api key used by the
+       rule while the rule was executing, or even before it executed,
+       on the first rule run.
+       this pr https://github.com/elastic/kibana/pull/68184
+       fixed this by finding the true source of a bug that required the manual
+       api key update, and removed the call to that function.
+
+       When the api key is updated before / while the rule is executing, the alert
+       executor no longer has access to a service to update the rule status
+       saved object in Elasticsearch. Because of this, we cannot set the rule into
+       a 'failure' state, so the user ends up seeing 'going to run' as that is the
+       last status set for the rule before it erupts in an error that cannot be
+       recorded inside of the executor.
+
+       This adds an e2e test for the backend to catch that in case
+       this pops up again elsewhere.
+      */
       it('should create a single rule with a rule_id and validate it ran successfully', async () => {
         const simpleRule = getSimpleRule();
         const { body } = await supertest

x-pack/test/detection_engine_api_integration/security_and_spaces/tests/find_statuses.ts

@@ -42,6 +42,25 @@ export default ({ getService }: FtrProviderContext): void => {
       expect(body).to.eql({});
     });
 
+    /*
+       This test is to ensure no future regressions introduced by the following scenario
+       a call to updateApiKey was invalidating the api key used by the
+       rule while the rule was executing, or even before it executed,
+       on the first rule run.
+       this pr https://github.com/elastic/kibana/pull/68184
+       fixed this by finding the true source of a bug that required the manual
+       api key update, and removed the call to that function.
+
+       When the api key is updated before / while the rule is executing, the alert
+       executor no longer has access to a service to update the rule status
+       saved object in Elasticsearch. Because of this, we cannot set the rule into
+       a 'failure' state, so the user ends up seeing 'going to run' as that is the
+       last status set for the rule before it erupts in an error that cannot be
+       recorded inside of the executor.
+
+       This adds an e2e test for the backend to catch that in case
+       this pops up again elsewhere.
+      */
     it('should return a single rule status when a single rule is loaded from a find status with defaults added', async () => {
       // add a single rule
       const { body: resBody } = await supertest