Jasca

Implementation of the XMPP Testing framwork “Scansion” in Rust

At the moment, jasca doesn't act as an xmpp client (unlike the original project) and only provides structs for comparing elements.

License

SPDX: MPL-2.0. See LICENSE file.

Parsing support

Language features are defined here:
https://matthewwild.co.uk/projects/scansion/usage/script-basics/

This library supports parsing the following:

• Metadata
  Lines starting with # at the beginning of the file. All metadata lines are optional. If a single line is found it's set as the title, the second lines are set as the description. Lines starting with ## right below will be added as tags. A description is not needed for tags to be added.
  • title: optional
  • description: optional
  • tags: optional
• Client
  • Attributes
    Following lines beginning with at least a tab (\t) character, in the form attr: value, and ending with a newline (\n). Any line that matches this format will be parsed and will be discarded if it doesn't match an actual client attribute.
    • jid: Expects a bare jid or a full jid. Will be converted to jid::FullJid (given a resource if necessary).
    • password
    • custom_host
    • custom_port: Expect a u16
• Component
  • Attributes
    Following lines beginning with at least a tab (\t) character, in the form attr: value, and ending with a newline (\n). Any line that matches this format will be parsed and will be discarded if it doesn't match an actual client attribute.
    • jid: Expects a jid composed of a single DomainPart. Fails during parsing if that's not the case.
    • custom_host
    • custom_port: Expect a u16
• Actions
  • 'connects'
  • 'disconnects'
  • 'sends:' / 'receives:'
    • A block of lines each starting with a tab (\t) after the action will be converted to a minidom::Element.
  • receives: nothing as the absence of received stanza.
• Variables in attributes
  • Bare Jid (${louise's JID})
  • Full Jid (${louise's full JID})
• Ignoring attribute values: {scansion:any}
• Comments
  Optional lines starting with a # or // and ending with a newline (\n). They get discarded in the output

ScanElement

ScanElement is a wrapper to minidom::Element that reimplements PartialEq. Most checks will happen in there, variables in attributes will also be read at this time.

PartialEq is only implemented for Element as it wouldn't make sense to compare two ScanElements.

This interface may change in the future as it doesn't allow returning a Result (errors may happen when parsing variables: missing from context, etc.). Currently when a referenced client doesn't exist in context, the comparison fails. If no context has been specified, comparison will go on, skipping variable handling.

minidom::Element requires every element to be namespaced and ScanElement has no special treatment for this. Be sure to include namespaces in your Elements. You may want to use Element::from_reader_with_prefixes.

Namespaced attributes aren't yet handled by minidom so scansion:strict also isn't treated in any special way.

Whitespace handling

To help with comparing stanzas transmitted over-the-wire that aren't pretty-printed, as they may be in scansion test files, special whitespace handling is done.

Text nodes containing only whitespace are considered insignificant, and removed from the comparison. Additionally in non-strict mode, unique child text nodes are trimmed (whitespace removed around text).

This is a bit restrictive, as it is for example possible to send messages including leading or ending newlines, the element in a message is free form after all. But for the purpose of testing with scansion this is not allowed.

Reporting bugs

Everything that's supported by upstream should be supported by this library.