[carl-baillargeon]

Description

Security advisory test docstrings now describe outcomes with the advisory assessment states instead of ANTA test statuses, and follow one consistent layout.

• Expected Results bullets use Not Affected, Affected, Mitigated, Inconclusive, and Error, in AdvisoryStatus order, and state only the condition for each outcome.
• Assessment rationale moves to a Notes section after Expected Results. Previously, rationale written after the bullets rendered inside the Expected Results block on the docs site.
• docs/security-advisory/tests.md explains how these states map to ANTA statuses.
• New test_advisory_docstring_layout unit test enforces the layout and labels.

Fixes #1757

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have run pre-commit for code linting and typing (pre-commit run)
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes (tox -e testenv)

Summary by CodeRabbit

• Documentation

  • Updated security advisory guidance to describe findings as Not Affected, Affected, Mitigated, Inconclusive, or Error, with clearer conditions for each outcome.
  • Clarified how advisory assessment states correspond to standard test statuses.

• Tests

  • Added checks that advisory documentation follows the expected section layout and uses valid, consistently ordered outcome labels.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Advisory test docstrings now describe assessment states instead of test pass and fail outcomes. The security advisory guide maps those states to ANTA test statuses, and a unit test checks advisory docstring structure and labels.

Changes: Advisory assessment documentation

Layer / File(s)	Summary
Update advisory outcome descriptions anta/tests/advisories/sa_*.py	Advisory expected-results text replaces Success and Failure labels with Not Affected and Affected. Some entries also clarify Inconclusive, Error, Mitigated, or vulnerability-specific conditions.
Document and check status labels docs/security-advisory/tests.md, tests/units/anta_tests/test_docstrings.py	The guide maps advisory assessment states to standard ANTA test statuses. A parametrized test checks allowed docstring layouts, bullet formatting, and state-label order.

Priority: Not assessed

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Other

Possibly related PRs

• aristanetworks/anta#1856: Both PRs edit SA178 expected-results documentation; the updated outcome text needs to correspond to the behavior changes described in this PR.
• aristanetworks/anta#1854: The decision names SA117 and SA153 for follow-up alignment, and this PR revises their expected-results text.

Suggested labels: rn: doc

Suggested reviewers: clausholbecharista, gmuloc

Merge Risk: Low · up to 866d4

Correct the two advisory descriptions before merging so affected and mitigated device assessments are documented accurately.

Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed]

Merging this PR will not alter performance

✅ 34 untouched benchmarks

---

_{Comparing carl-baillargeon:doc/1757-psirt-sa-docstrings (866d441) with main (a6de128)}

[gmuloc]

LGTM except couple of nits

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.39%. Comparing base (55b74fb) to head (866d441).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1857      +/-   ##
==========================================
+ Coverage   95.38%   95.39%   +0.01%     
==========================================
  Files         172      172              
  Lines       17220    17261      +41     
  Branches     2636     2644       +8     
==========================================
+ Hits        16425    16466      +41     
  Misses        480      480              
  Partials      315      315              

Components	Coverage Δ
CLI	93.81% <ø> (ø)
asynceapi	84.86% <ø> (ø)
ANTA Core	92.28% <ø> (ø)
ANTA Tests	98.68% <ø> (+<0.01%)	⬆️

Files with missing lines	Coverage Δ
anta/tests/advisories/sa_117.py	100.00% <ø> (ø)
anta/tests/advisories/sa_140.py	100.00% <ø> (ø)
anta/tests/advisories/sa_142.py	88.81% <ø> (ø)
anta/tests/advisories/sa_146.py	89.36% <ø> (ø)
anta/tests/advisories/sa_147.py	90.58% <ø> (ø)
anta/tests/advisories/sa_149.py	96.42% <ø> (ø)
anta/tests/advisories/sa_150.py	100.00% <ø> (ø)
anta/tests/advisories/sa_151.py	100.00% <ø> (ø)
anta/tests/advisories/sa_152.py	100.00% <ø> (ø)
anta/tests/advisories/sa_153.py	100.00% <ø> (ø)
... and 25 more

... and 9 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.