13.5.  Single and Double Quotation Marks inside Strings

The meaning of double quotes in XML, XPath and Java

Strings inside XML Tags are enclosed by a start tag and an end tag. So the content may have any combination of single and double quotes.

The values of XML attributes are delimited by either single or double quotes. This means that you can use double quotes as content when you use single quotes as the delimter and vice versa. You can also use the entities ' and " as a content.

An arbitrary use of single and double quotes in XPath expressions is not possible, even if you use entities. It is recommended to use single quotes.

In Java strings will be enclosed in double quotes. And because PDFUnit-XML tests will first be converted into Java code and then executed as a Java program, double quotes must be escaped by a backslash when they are part of the content.

Different types of quotes

Important Notice: The term Quote has different meanings as the following picture shows:

“English“ and „German“ style quotation marks do not disturb the execution of tests. But during the creation of a test you could have problems typing them with your editor. Hint: copy the required quotation marks from a word-processor or an exisiting PDF document and paste them into your XML editor.

The "programmers double quotes" need special attention because they are used as string delimiters in Java. The following paragraphs and examples go into detail about this. They are all based on the following document:

Quotes in Tags

Single quotes in PDFUnit tags cause no problems. But double quotes must be escaped with a backslash:

<testcase name="tagWith_SingleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasText on="FIRST_PAGE">
      <containing>Example 1: 'single quotes'</containing>
    </hasText>
  </assertThat>
</testcase>
<testcase name="tagWith_GermanDoubleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasText on="FIRST_PAGE">
      <containing>Example 2: „German double quotes“</containing>
    </hasText>
  </assertThat>
</testcase>
<testcase name="tagWith_EnglishDoubleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasText on="FIRST_PAGE">
      <containing>Example 3: “English double quotes“</containing>
    </hasText>
  </assertThat>
</testcase>
<testcase name="tagWith_ProgrammersDoubleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasText on="FIRST_PAGE">
      <containing>Example 4: \"programmers double quotes\"</containing>
    </hasText>
  </assertThat>
</testcase>
<testcase name="tagWith_DoubleAndSingleQuotes_1">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasText on="FIRST_PAGE">
      <containing>
        Example 5: \"double quotes outside, 'single quotes' inside\"
      </containing>
    </hasText>
  </assertThat>
</testcase>
<testcase name="tagWith_DoubleAndSingleQuotes_2">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasText on="FIRST_PAGE">
      <containing>Example 6: 'single quotes outside, \"double quotes\" inside'</containing>
    </hasText>
  </assertThat>
</testcase>

Quotes in Attributes

Single quotes in attributes can be used without restriction, when the attribute is enclosed by double-quotes. And vice versa.

The following examples show a valid usage of single and double quotes in attributes.

<testcase name="attributeWith_DoubleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasBookmark withLabel='"Double Quote"-Chapter' />
  </assertThat>
</testcase>
<testcase name="attributeWith_SingleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasBookmark withLabel="'Single Quote'-Chapter" />
  </assertThat>
</testcase>

But you may not use not single and double quotes at the same time within a string, not even as entities. The next examples shows an invalid usage of quotes:

<!-- 
  This example fails, because single- and double-quotes were used 
  inside the expected label.
-->

<testcase name="attributeWith_SingleDoubleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasBookmark withLabel="'Single &quot;Double&quot; Quote'-Chapter" />
  </assertThat>
</testcase>

Quotes in XPath-Expressions

The XML code which defines your test is first converted into Java code. This then evaluates the XPath expressions. So the same restrictions for using quotes in XPath expressions exists as for strings described above.

The following example can be converted into Java code but results in this runtime error: One of the parameter contains single and double quote. You may use only one kind of quote.

<testcase name="attributeWithXPath_DoubleQuotes_1">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasBookmarks>
      <matchingXPath expr="count(//Title[.='\&quot;Double Quote\&quot;-Chapter']) = 1" />
    </hasBookmarks>
  </assertThat>
</testcase>

You can avoid this error by simply writing the XPath expression without double quotes:

<testcase name="attributeWithXPath_DoubleQuotes_2">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasBookmarks>
      <matchingXPath expr="count(//Title[contains(., 'Double Quote')]) = 1" />
      <matchingXPath expr="count(//Title[contains(., 'Chapter')]) = 4" />
    </hasBookmarks>
  </assertThat>
</testcase>

Quotes in Regular Expressions

Due to the evaluation of regular expressions via the intermediate step of generated Java code, you must escape double quotes:

<testcase name="regex_tag_DoubleQuotes">
  <assertThat testDocument="quotes/single-and-doublequotes.pdf">
    <hasText on="FIRST_PAGE">
      <matchingRegex>.*\"double.*</matchingRegex>
    </hasText>
  </assertThat>
</testcase>