Renamed tests and added chaining choice states info in docstings

Author: ca-nguyen

Diff for: src/stepfunctions/steps/states.py

@@ -221,9 +221,8 @@ def next(self, next_step):
         if self.type in ('Succeed', 'Fail'):
             raise ValueError('Unexpected State instance `{step}`, State type `{state_type}` does not support method `next`.'.format(step=next_step, state_type=self.type))
 
-        # By design, Choice states do not have the Next field. Their purpose is to define conditional transitions based
-        # on a set of Choice Rules. They can be viewed as an advanced Next field with multiple possible transitions.
-        # default_choice() sets the default transition to use in the case where none of the Choice Rules are met.
+        # By design, Choice states do not have the Next field. When used in a chain, the subsequent step becomes the
+        # default choice that executes if none of the specified rules match.
         # See language spec for more info: https://states-language.net/spec.html#choice-state
         if self.type is 'Choice':
             if self.default is not None:
@@ -417,7 +416,7 @@ def allowed_fields(self):
 class Choice(State):
 
     """
-    Choice state adds branching logic to a state machine. The state holds a list of *rule* and *next_step* pairs. The interpreter attempts pattern-matches against the rules in list order and transitions to the state or chain specified in the *next_step* field on the first *rule* where there is an exact match between the input value and a member of the comparison-operator array.
+    Choice state adds branching logic to a state machine. The state holds a list of *rule* and *next_step* pairs. The interpreter attempts pattern-matches against the rules in list order and transitions to the state or chain specified in the *next_step* field on the first *rule* where there is an exact match between the input value and a member of the comparison-operator array. When used in a chain, the subsequent step becomes the default choice that executes if none of the specified rules match.
     """
 
     def __init__(self, state_id, **kwargs):

Diff for: tests/unit/test_steps.py

@@ -368,7 +368,7 @@ def test_chaining_steps():
     assert s2.next_step == s3
 
 
-def test_chaining_choice():
+def test_chaining_choice_sets_default_field():
     s1_pass = Pass('Step - One')
     s2_choice = Choice('Step - Two')
     s3_pass = Pass('Step - Three')
@@ -381,7 +381,7 @@ def test_chaining_choice():
     assert s3_pass.next_step is None
 
 
-def test_chaining_choice_with_default(caplog):
+def test_chaining_choice_with_existing_default_overrides_value(caplog):
     s1_pass = Pass('Step - One')
     s2_choice = Choice('Step - Two')
     s3_pass = Pass('Step - Three')