# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Test Observer Test Executions API
  version: 1.0.0
extends: openapi/canonical-test-executions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/v1/test-executions/end-test'].put
  update:
    x-apievangelist-phrasing:
      intent: Finish a test execution and submit its results
      effect: write
      questions:
      - How do I close out a test run and report its results to Test Observer?
      - Can I attach the CI job link when marking a test execution as ended?
      instructions:
      - text: End the test execution for CI job {ci_link} and submit results {test_results}.
        slots:
          ci_link: requestBody.ci_link
          test_results: requestBody.test_results
      - text: Mark the run at {ci_link} finished with results {test_results} and C3 link {c3_link}.
        slots:
          ci_link: requestBody.ci_link
          test_results: requestBody.test_results
          c3_link: requestBody.c3_link
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}/test-results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the test results of a test execution
      effect: read
      questions:
      - Which individual test cases passed or failed in a given test execution?
      - Can I pull all results recorded for one test run?
      instructions:
      - text: Show the test results for test execution {id}.
        slots:
          id: path.id
      - text: List every test case outcome recorded under execution {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}/test-results'].post
  update:
    x-apievangelist-phrasing:
      intent: Add test results to a test execution
      effect: write
      questions:
      - How do I upload test case results to a test execution that is still running?
      - Can I post results to a run before ending it?
      instructions:
      - text: Post these test results to test execution {id}.
        slots:
          id: path.id
      - text: Upload a batch of test case outcomes to execution {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}/links'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a labelled link to a test execution
      effect: write
      questions:
      - How do I add a link, like a log or dashboard URL, to a test execution?
      - Can each link on a test run carry its own label?
      instructions:
      - text: Add link {url} labelled {label} to test execution {id}.
        slots:
          url: requestBody.url
          label: requestBody.label
          id: path.id
      - text: Attach the logs at {url} to execution {id} as {label}.
        slots:
          url: requestBody.url
          id: path.id
          label: requestBody.label
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}/links/{link_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a link from a test execution
      effect: destructive
      questions:
      - How do I delete an outdated link from a test run?
      - Can I remove one attached URL without touching the other links on an execution?
      instructions:
      - text: Delete link {link_id} from test execution {id}.
        slots:
          link_id: path.link_id
          id: path.id
      - text: Remove the attached URL {link_id} on execution {id}.
        slots:
          link_id: path.link_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/reruns'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending test execution rerun requests
      effect: read
      questions:
      - Which test executions have been asked to run again?
      - Can I see rerun requests only for a given environment or architecture?
      instructions:
      - text: List rerun requests for the {family} family.
        slots:
          family: query.family
      - text: Show pending reruns on environment {environment} for architecture {environment_architecture}.
        slots:
          environment: query.environment
          environment_architecture: query.environment_architecture
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/reruns'].post
  update:
    x-apievangelist-phrasing:
      intent: Request reruns of test executions
      effect: write
      questions:
      - How do I ask for failed test executions to be run again?
      - Can I request reruns quietly, without notifying anyone, and set a priority?
      instructions:
      - text: Request a rerun of test executions {test_execution_ids}.
        slots:
          test_execution_ids: requestBody.test_execution_ids
      - text: Queue reruns for executions {test_execution_ids} at priority {priority}, silently.
        slots:
          test_execution_ids: requestBody.test_execution_ids
          priority: requestBody.priority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/reruns'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel rerun requests for test executions
      effect: destructive
      questions:
      - How do I withdraw a rerun I requested by mistake?
      - Can I cancel reruns in bulk using result filters?
      instructions:
      - text: Cancel the rerun requests for executions {test_execution_ids}.
        slots:
          test_execution_ids: requestBody.test_execution_ids
      - text: Delete rerun requests matching execution filters {test_executions_filters}.
        slots:
          test_executions_filters: requestBody.test_executions_filters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/reruns/details'].get
  update:
    x-apievangelist-phrasing:
      intent: Get detailed rerun requests for a family
      effect: read
      questions:
      - What detail is available on reruns requested for a snap or deb family?
      - Can I page through rerun details filtered by priority?
      instructions:
      - text: Show detailed rerun requests for family {family}.
        slots:
          family: query.family
      - text: Get rerun details for {family} at priority {priority}, {limit} per page.
        slots:
          family: query.family
          priority: query.priority
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a test execution
      effect: read
      questions:
      - What is the status and CI link of a particular test execution?
      - Can I retrieve one test run's details by its id?
      instructions:
      - text: Show test execution {id}.
        slots:
          id: path.id
      - text: Get the status, environment and links of run {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a test execution's status or links
      effect: write
      questions:
      - How do I change the status of a test execution after it started?
      - Can I update the CI or C3 link on an existing test run?
      instructions:
      - text: Set the status of test execution {id} to {status}.
        slots:
          id: path.id
          status: requestBody.status
      - text: Update execution {id} with CI link {ci_link} and C3 link {c3_link}.
        slots:
          id: path.id
          ci_link: requestBody.ci_link
          c3_link: requestBody.c3_link
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions'].get
  update:
    x-apievangelist-phrasing:
      intent: Search test executions with filters
      effect: read
      questions:
      - How do I find all failed test executions for an artefact in a given environment?
      - Can I search only the latest executions within a date range?
      - Which test runs are assigned to a particular reviewer?
      instructions:
      - text: Search test executions for artefacts {artefacts} in environments {environments}.
        slots:
          artefacts: query.artefacts
          environments: query.environments
      - text: Find executions with status {test_execution_statuses} between {from_date} and {until_date}.
        slots:
          test_execution_statuses: query.test_execution_statuses
          from_date: query.from_date
          until_date: query.until_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/start-test'].put
  update:
    x-apievangelist-phrasing:
      intent: Start a new test execution
      effect: write
      questions:
      - How do I register that a test run has begun in Test Observer?
      - What happens when a CI job signals the start of a test execution?
      instructions:
      - text: Start a new test execution for this artefact build.
      - text: Register the beginning of a test run from my CI job.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}/status_update'].get
  update:
    x-apievangelist-phrasing:
      intent: Get status events of a test execution
      effect: read
      questions:
      - What progress events has a running test execution reported?
      - Can I see the event timeline of a test run?
      instructions:
      - text: Show the status update events for test execution {id}.
        slots:
          id: path.id
      - text: Get the progress timeline of run {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}/status_update'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace the status events of a test execution
      effect: write
      questions:
      - How do I overwrite the whole list of status events on a test run?
      - Can I reset a test execution's event log with a new set of events?
      instructions:
      - text: Replace all status events on test execution {id} with {events}.
        slots:
          id: path.id
          events: requestBody.events
      - text: Overwrite the event log of run {id} using events {events}.
        slots:
          id: path.id
          events: requestBody.events
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/test-executions/{id}/status_update'].post
  update:
    x-apievangelist-phrasing:
      intent: Report new status events for a test execution
      effect: write
      questions:
      - How does a test agent post progress events while a run is underway?
      - Can I append status events to a test execution without replacing earlier ones?
      instructions:
      - text: Post status events {events} to test execution {id}.
        slots:
          events: requestBody.events
          id: path.id
      - text: Append progress events {events} to the timeline of run {id}.
        slots:
          events: requestBody.events
          id: path.id
      method: generated
      generated: '2026-09-26'