Stage weight must be unique to pass the validation

[escopecz]

The API Library tests started to fail after a stage validation was added:

There were 8 failures:

1) Mautic\Tests\Api\CampaignsTest::testEditPatch
The response has unexpected status code (400).

Response: {"errors":[{"code":400,"message":"publishUp: Please enter a valid date and time.","details":{"publishUp":["Please enter a valid date and time."]}}]}

Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:108
/home/runner/work/api-library/api-library/tests/Api/CampaignsTest.php:244

2) Mautic\Tests\Api\CampaignsTest::testEventAndSourceDeleteViaPut
The response has unexpected status code (400).

Response: {"errors":[{"code":400,"message":"publishUp: Please enter a valid date and time.","details":{"publishUp":["Please enter a valid date and time."]}}]}

Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:108
/home/runner/work/api-library/api-library/tests/Api/CampaignsTest.php:349

3) Mautic\Tests\Api\StagesTest::testGetListOfSpecificIds
The response has unexpected status code (400).

Response: {"errors":[{"code":400,"message":"weight: Another stage with this weight already exists.","details":{"weight":["Another stage with this weight already exists."]}}]}
Payload: {
    "name": "test"
}
Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:182
/home/runner/work/api-library/api-library/tests/Api/StagesTest.php:31

4) Mautic\Tests\Api\StagesTest::testCreateGetAndDelete
The response has unexpected status code (400).

Response: {"errors":[{"code":400,"message":"weight: Another stage with this weight already exists.","details":{"weight":["Another stage with this weight already exists."]}}]}

Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:241
/home/runner/work/api-library/api-library/tests/Api/StagesTest.php:36

5) Mautic\Tests\Api\StagesTest::testEditPatch
The response has unexpected status code (400).

Response: {"errors":[{"code":400,"message":"weight: Another stage with this weight already exists.","details":{"weight":["Another stage with this weight already exists."]}}]}

Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:108
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:313
/home/runner/work/api-library/api-library/tests/Api/StagesTest.php:44

6) Mautic\Tests\Api\StagesTest::testEditPut
The response has unexpected status code (400).

Response: {"errors":[{"code":400,"message":"weight: Another stage with this weight already exists.","details":{"weight":["Another stage with this weight already exists."]}}]}

Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:108
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:325
/home/runner/work/api-library/api-library/tests/Api/StagesTest.php:49

7) Mautic\Tests\Api\StagesTest::testAddAndRemove
The response has unexpected status code (400).

Response: {"errors":[{"code":400,"message":"weight: Another stage with this weight already exists.","details":{"weight":["Another stage with this weight already exists."]}}]}

Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:108
/home/runner/work/api-library/api-library/tests/Api/StagesTest.php:62

8) Mautic\Tests\Api\StagesTest::testBatchEndpoints
weight: Another stage with this weight already exists.; weight: Another stage with this weight already exists.; weight: Another stage with this weight already exists.

Failed asserting that false is true.

/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:93
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:108
/home/runner/work/api-library/api-library/tests/Api/MauticApiTestCase.php:270
/home/runner/work/api-library/api-library/tests/Api/StagesTest.php:84

FAILURES!
Tests: 315, Assertions: 5078, Failures: 8, Skipped: 7.

The campaign related failures are addressed in mautic/mautic#16264

[promptless-for-oss]

Promptless prepared a documentation update related to this change.

Triggered by api-library PR #348

While this PR is a test-only change, it surfaces an API-consumer-visible constraint: creating or editing a Stage with a duplicate weight now returns 400 weight: Another stage with this weight already exists. The Stages REST API reference didn't mention this, so we documented the uniqueness requirement and the possible 400 response for the Create and Edit Stage endpoints.

Review: Document unique stage weight requirement in Stages REST API

[promptless-for-oss]

Promptless prepared a documentation update related to this change.

Triggered by api-library PR #348

While reviewing the stage weight uniqueness constraint surfaced by this PR, we found a contradiction in the user-facing Stages documentation: the "Moving Contacts between Stages" section still stated that multiple Stages across funnels could share the same weight, which conflicts with the validation requiring each Stage's weight to be unique. We corrected that note.

Review: Correct contradictory note on unique Stage weights