Scenario (javarosa 5.1.0 API)

java.lang.Object
- org.javarosa.test.Scenario

```
public class Scenario
extends Object
```
Warning This class is probably incomplete. If your testing requirements aren't met by this class, please, ask around and let's try to make this tool awesome together.
This class helps writing JavaRosa tests. It provides two separate APIs:
- A static, declarative API that lets the test author define the state of a form in a given time.
- A dynamic, imperative API that lets the test author fill the form as the user would do, by controlling the flow while filling questions. These methods return the Scenario to be able to chain compatible methods.
All the methods that accept a String xpath argument, support an enhanced version of xpath with the following perks and limitations:
- Only supports absolute xpaths
- Supports adding the index (zero-indexed) of a repeat instance by suffixing it between brackets. Example that would select the fourth instance of the /foo/bar repeat: /foo/bar[3]

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Scenario.AnswerResult

Nested Classes
Modifier and Type	Class and Description
`static class`	`Scenario.AnswerResult`

Field Summary

Fields
Modifier and Type Field and Description

static FormIndex BEGINNING_OF_FORM

Fields
Modifier and Type	Field and Description
`static FormIndex`	`BEGINNING_OF_FORM`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Scenario.AnswerResult`	`answer(boolean value)` Answers the question at the form index
`Scenario.AnswerResult`	`answer(char value)` Answers the question at the form index
`Scenario.AnswerResult`	`answer(double value)` Answers the question at the form index
`Scenario.AnswerResult`	`answer(int value)` Answers the question at the form index
`Scenario.AnswerResult`	`answer(List<String> values)` Answers the question at the form index
`Scenario.AnswerResult`	`answer(LocalDate value)` Answers the question at the form index
`Scenario.AnswerResult`	`answer(SelectChoice choice)`
`Scenario.AnswerResult`	`answer(String value)` Answers the question at the form index
`Scenario.AnswerResult`	`answer(String xPath, boolean value)` Answers with a boolean value the question at the form index corresponding to the provided reference.
`Scenario.AnswerResult`	`answer(String xPath, double value)` Answers with an double value the question at the form index corresponding to the provided reference.
`Scenario.AnswerResult`	`answer(String xPath, int value)` Answers with an integer value the question at the form index corresponding to the provided reference.
`Scenario.AnswerResult`	`answer(String xPath, String... selectionValues)` Answers with a list of string values the question at the form index corresponding to the provided reference.
`Scenario.AnswerResult`	`answer(String xPath, String value)` Answers with a string value the question at the form index corresponding to the provided reference.
`<T extends IAnswerData> T`	`answerOf(String xPath)`
`boolean`	`atQuestion()`
`boolean`	`atTheEndOfForm()`
`List<SelectChoice>`	`choicesOf(String xPath)` Returns the list of choices of the <select> or <select1> form controls.
`int`	`countRepeatInstancesOf(String xPath)`
`static @NotNull FormDef`	`createFormDef(File formFile)`
`static FormDef`	`createFormDef(String formName, XFormsElement form)`
`Scenario`	`createNewRepeat()` Creates a new repeat group instance.
`Scenario`	`createNewRepeat(String xPath)` Creates a new repeat group instance in the group corresponding to the provided xPath reference
`TreeReference`	`expandSingle(TreeReference reference)` Returns the single expanded reference of the provided reference.
`void`	`finalizeInstance()`
`TreeElement`	`getAnswerNode(String xPath)`
`FormIndex`	`getCurrentIndex()`
`EvaluationContext`	`getEvaluationContext()`
`FormDef`	`getFormDef()`
`FormEntryController`	`getFormEntryController()`
`FormEntryPrompt`	`getFormEntryPromptAtIndex()`
`QuestionDef`	`getQuestionAtIndex()`
`static TreeReference`	`getRef(String xpath)` Returns a TreeReference from the provided xpath string.
`ValidateOutcome`	`getValidationOutcome()`
`FormIndex`	`indexOf(String xPath)`
`void`	`init(boolean newInstance)`
`static Scenario`	`init(File formFile)` Initializes the Scenario with the form at the provided path
`static Scenario`	`init(FormDef formDef)`
`static Scenario`	`init(String formFileName)` Initializes the Scenario with provided form filename.
`static Scenario`	`init(String formName, XFormsElement form)` Initializes the Scenario using a form defined using the DSL in XFormsElement
`static Scenario`	`init(String formName, XFormsElement form, Function<FormDef,FormEntryController> controllerSupplier)`
`void`	`jumpToBeginningOfForm()` Jump to the beginning of the form.
`void`	`newInstance()` Prepares the form to answer a new blank instance
`int`	`next()` Jump to the next event.
`void`	`next(int amount)` Jump the provided amount of times to the next event.
`TreeReference`	`nextRef()`
`Scenario`	`onDagEvent(Consumer<Event> callback)` Sets a callback that will be called every time there's a DAG event
`int`	`prev()`
`TreeReference`	`refAtIndex()`
`Scenario`	`removeRepeat(String xPath)` Removes the repeat instance corresponding to the provided reference
`Scenario`	`serializeAndDeserializeForm()` Returns a new Scenario instance using a new form obtained by serializing and deserializing the form being used by this instance.
`Scenario`	`serializeAndDeserializeInstance(XFormsElement form)`
`void`	`setLanguage(String language)` Sets the language of the form for itext translations
`void`	`trace(String msg)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - BEGINNING_OF_FORM
```
public static final FormIndex BEGINNING_OF_FORM
```
- Method Detail
  - init
```
public void init(boolean newInstance)
```
  - getFormDef
```
public FormDef getFormDef()
```
  - indexOf
```
public FormIndex indexOf(String xPath)
```
  - getCurrentIndex
```
public FormIndex getCurrentIndex()
```
  - getValidationOutcome
```
public ValidateOutcome getValidationOutcome()
```
  - getRef
```
public static TreeReference getRef(String xpath)
```
    Returns a TreeReference from the provided xpath string.
    This method parses the provided xpath string using the XPathParseTool and postprocesses the resulting reference to account for multiplicity predicates.
    JavaRosa relies on negative multiplicity values to identify special nodes (such as templates for repeat groups), unbound references (to refer to a nodeset), and on positive multiplicity values to specify individual repeat group instances.
    These multiplicities are declared as numeric predicates such as [2], which are translated to predicates by the XPath parser. This is problematic because JavaRosa will eventually try to evaluate all predicates declared in references when resolving elements of an instance and nodes won't ever match the predicates used to define multiplicity.
    For this reason, this method will try to detect these predicates, turn them into multiplicity values, and remove them from the output reference.
    These multiplicities use 1-based indexing to match user-facing XPath expressions. To match JR's internal representation, 1 is subtracted. When using the result of this method for test assertions against FormIndex.getReference() we need to specify multiplicity on all steps. For example the following would pass for a form index pointing at a question at the top level of the form: assertThat(formIndex.getReference(), is(getRef("/data/question[1]"))); This is because getRef has no way of knowing if a node without multiplicity ([x]) is a question/group or an unbounded repeat (which would have a multiplicity of -1). Adding the explicit [1] lets getRef know that the node is not an unbounded repeat and that it, like a real question or group, should have the default multiplicity of 0.
  - newInstance
```
public void newInstance()
```
    Prepares the form to answer a new blank instance
  - setLanguage
```
public void setLanguage(String language)
```
    Sets the language of the form for itext translations
  - getEvaluationContext
```
public EvaluationContext getEvaluationContext()
```
  - onDagEvent
```
public Scenario onDagEvent(Consumer<Event> callback)
```
    Sets a callback that will be called every time there's a DAG event
  - serializeAndDeserializeForm
```
public Scenario serializeAndDeserializeForm()
                                     throws IOException,
                                            DeserializationException
```
    Returns a new Scenario instance using a new form obtained by serializing and deserializing the form being used by this instance.
    
    Throws:
    
    IOException
    
    DeserializationException
  - serializeAndDeserializeInstance
```
public Scenario serializeAndDeserializeInstance(XFormsElement form)
                                         throws IOException,
                                                XFormParser.ParseException
```
    Throws:
    
    IOException
    
    XFormParser.ParseException
  - expandSingle
```
public TreeReference expandSingle(TreeReference reference)
```
    Returns the single expanded reference of the provided reference.
    This method assumes the provided reference will only be expanded to exactly one reference, which is useful to go from unbound references to fully qualified references that wouldn't match existing form indexes otherwise.
  - trace
```
public void trace(String msg)
```
  - finalizeInstance
```
public void finalizeInstance()
```
  - getFormEntryController
```
public FormEntryController getFormEntryController()
```
  - init
```
public static Scenario init(String formName,
                            XFormsElement form)
                     throws IOException,
                            XFormParser.ParseException
```
    Initializes the Scenario using a form defined using the DSL in XFormsElement
    
    Throws:
    
    IOException
    
    XFormParser.ParseException
  - init
```
public static Scenario init(String formName,
                            XFormsElement form,
                            Function<FormDef,FormEntryController> controllerSupplier)
                     throws IOException,
                            XFormParser.ParseException
```
    Throws:
    
    IOException
    
    XFormParser.ParseException
  - createFormDef
```
public static FormDef createFormDef(String formName,
                                    XFormsElement form)
                             throws IOException,
                                    XFormParser.ParseException
```
    Throws:
    
    IOException
    
    XFormParser.ParseException
  - init
```
public static Scenario init(String formFileName)
                     throws XFormParser.ParseException
```
    Initializes the Scenario with provided form filename.
    A form with the provided filename must exist in the classpath
    
    Throws:
    
    XFormParser.ParseException
  - init
```
public static Scenario init(File formFile)
                     throws XFormParser.ParseException
```
    Initializes the Scenario with the form at the provided path
    
    Throws:
    
    XFormParser.ParseException
  - init
```
public static Scenario init(FormDef formDef)
                     throws XFormParser.ParseException
```
    Throws:
    
    XFormParser.ParseException
  - createFormDef
```
@NotNull
public static @NotNull FormDef createFormDef(File formFile)
                                               throws XFormParser.ParseException
```
    Throws:
    
    XFormParser.ParseException
  - answer
```
public Scenario.AnswerResult answer(String xPath,
                                    String value)
```
    Answers with a string value the question at the form index corresponding to the provided reference.
    This method has side effects: - It will create all the required middle and end repeat group instances - It changes the current form index
  - answer
```
public Scenario.AnswerResult answer(String xPath,
                                    String... selectionValues)
```
    Answers with a list of string values the question at the form index corresponding to the provided reference.
    This method has side effects: - It will create all the required middle and end repeat group instances - It changes the current form index
  - answer
```
public Scenario.AnswerResult answer(String xPath,
                                    int value)
```
    Answers with an integer value the question at the form index corresponding to the provided reference.
    This method has side effects: - It will create all the required middle and end repeat group instances - It changes the current form index
  - answer
```
public Scenario.AnswerResult answer(String xPath,
                                    double value)
```
    Answers with an double value the question at the form index corresponding to the provided reference.
    This method has side effects: - It will create all the required middle and end repeat group instances - It changes the current form index
  - answer
```
public Scenario.AnswerResult answer(String xPath,
                                    boolean value)
```
    Answers with a boolean value the question at the form index corresponding to the provided reference.
    This method has side effects: - It will create all the required middle and end repeat group instances - It changes the current form index
  - answer
```
public Scenario.AnswerResult answer(String value)
```
    Answers the question at the form index
  - answer
```
public Scenario.AnswerResult answer(List<String> values)
```
    Answers the question at the form index
  - answer
```
public Scenario.AnswerResult answer(SelectChoice choice)
```
  - answer
```
public Scenario.AnswerResult answer(int value)
```
    Answers the question at the form index
  - answer
```
public Scenario.AnswerResult answer(double value)
```
    Answers the question at the form index
  - answer
```
public Scenario.AnswerResult answer(char value)
```
    Answers the question at the form index
  - answer
```
public Scenario.AnswerResult answer(LocalDate value)
```
    Answers the question at the form index
  - answer
```
public Scenario.AnswerResult answer(boolean value)
```
    Answers the question at the form index
  - removeRepeat
```
public Scenario removeRepeat(String xPath)
```
    Removes the repeat instance corresponding to the provided reference
  - createNewRepeat
```
public Scenario createNewRepeat()
```
    Creates a new repeat group instance. The form index must be at a create new repeat group question
  - createNewRepeat
```
public Scenario createNewRepeat(String xPath)
```
    Creates a new repeat group instance in the group corresponding to the provided xPath reference
  - next
```
public int next()
```
    Jump to the next event.
    Side effects: - This method updates the form index - This method leaves log traces
  - prev
```
public int prev()
```
  - next
```
public void next(int amount)
```
    Jump the provided amount of times to the next event.
    Side effects: - This method updates the form index - This method leaves log traces
  - jumpToBeginningOfForm
```
public void jumpToBeginningOfForm()
```
    Jump to the beginning of the form.
    Side effects: - This method updates the form index - This method leaves log traces
  - atTheEndOfForm
```
public boolean atTheEndOfForm()
```
  - nextRef
```
public TreeReference nextRef()
```
  - refAtIndex
```
public TreeReference refAtIndex()
```
  - atQuestion
```
public boolean atQuestion()
```
  - getQuestionAtIndex
```
public QuestionDef getQuestionAtIndex()
```
  - getFormEntryPromptAtIndex
```
public FormEntryPrompt getFormEntryPromptAtIndex()
```
  - answerOf
```
public <T extends IAnswerData> T answerOf(String xPath)
```
  - countRepeatInstancesOf
```
public int countRepeatInstancesOf(String xPath)
```
  - choicesOf
```
public List<SelectChoice> choicesOf(String xPath)
```
    Returns the list of choices of the <select> or <select1> form controls.
    This method ensures that any dynamic choice lists are populated to reflect the status of the form (already answered questions, etc.).
  - getAnswerNode
```
public TreeElement getAnswerNode(String xPath)
```

Class Scenario

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BEGINNING_OF_FORM

Method Detail

init

getFormDef

indexOf

getCurrentIndex

getValidationOutcome

getRef

newInstance

setLanguage

getEvaluationContext

onDagEvent

serializeAndDeserializeForm

serializeAndDeserializeInstance

expandSingle

trace

finalizeInstance

getFormEntryController

init

init

createFormDef

init

init

init

createFormDef

answer

answer

answer

answer

answer

answer

answer

answer

answer

answer

answer

answer

answer

removeRepeat

createNewRepeat

createNewRepeat

next

prev

next

jumpToBeginningOfForm

atTheEndOfForm

nextRef

refAtIndex

atQuestion

getQuestionAtIndex

getFormEntryPromptAtIndex

answerOf

countRepeatInstancesOf

choicesOf

getAnswerNode