Manual Testing

When making changes to Draft.js component code (/src/component) it is important to test the change within the browser. Moreover, since the Draft.js userbase spans a broad range of browsers, platforms, and locales, the number of permutations is quite high.

This document details basic manual test specs that contributors should apply to their proposed pull requests. The general guideline is to assume that merged pull requests will be live in production within a week, for over a billion users on facebook.com. Thus, while contributors are not expected to test every spec for every change, they should aim to be as thorough as possible when testing changes.

FAQ

Which browsers should I test?

• The latest versions of Chrome, Firefox, Safari.
• IE 10 and 11, plus the latest version of Edge.
• iOS Safari and Chrome, Android browsers
  • Draft.js does not officially support mobile browsers at this point, so this can currently be considered optional. The framework is moving toward full mobile support, however, so testing on mobile is strongly recommended.

For the most part, changes should be testable on your preferred operating system. However, if you are making changes that may affect IME or spellcheck handling, please test OSX and Windows if possible.

Can this be automated?

It would be awesome to automate as much of this testing as possible, but there are currently no automated browser tests for the project. Ideas and contributions are welcome. It may also not be possible to automate testing of some flows, such as IME input.

Can this be streamlined?

It would also be awesome to a testing playground to streamline this process as much as possible. I.e., a website within the Draft.js repository that provides a series of example editors with side-by-side instructions for performing a manual test spec on each.

In this way, developers could quickly run through a series of manual tests and immediately observe success or failure. Contact @hellendag if you are interested in helping with this!

You forgot something! Can I add some more specs to this list?

Yes! This is not an exhaustive list, despite its length. If you have ideas for other basic tests that should be included here, feel free to add them.

Examples

• Please load and briefly play with each of the examples included in the github project..

Rendering

Load an example rich editor. Verify proper rendering of:

• Placeholder text
  • Note: placeholder can be rendered differently via CSS when editor is focused.
• Characters and newlines
• Inline styles, including overlapping inline styles
• Block-level styles
  • Unstyled, headers, blockquotes, etc.
  • List items, including indented items
• Decorated ranges, e.g. links
  • Decorated entities
  • Decorators that do not use entities, e.g. tweet handles or hashtags
• Custom block components, e.g. TeX editor
• Non-Latin character sets and emoji

It is also recommended that you test readOnly mode to sanity check proper rendering of static content.

Simple Edits

Load an example editor and place cursor into it.

Typing

• Add characters
• Backspace and forward-delete characters
• Backspace and/or forward-delete to merge two blocks together
• Press return to add a new block
• Select multiple characters or blocks, then:
  • Add characters to replace entire selection
  • Backspace and forward-delete entire selection
• Add and remove characters on decorated or styled ranges

Styling

Load an example rich editor and add text.

• Select text, apply inline style. Verify application of style.
• Remove inline style. Verify removal.
• Repeat with overlapping styles, verify proper application and removal.
• Set and unset block types.
• Indent and unindent list items.
  • Verify proper list bulleting and numbering for multi-level lists

Keyboard Shortcuts

See default list of key bindings. Commands below are listed as OSX commands unless otherwise noted. For many commands, use Ctrl in Windows instead.

Load an example rich editor and add text.

Styles

• Cmd+B: Apply and remove bold style
• Cmd+I: Apply and remove italic style
• Cmd+J (specific to Draft): Apply and remove code style
  • For collapsed selection, sets the entire block to be code style. For multi-character selection, sets only the selected range.
• Cmd+U: Apply and remove underline style

Deletion

• Ctrl+D: Forward delete one character
• Ctrl+H: Backspace one character
• Ctrl+W (OSX): Backspace word
• Cmd+Backspace (OSX): Backspace to start of line
• Alt+Delete (OSX): Forward delete word
• Alt+Backspace (OSX): Backspace word

Edits

• Ctrl+M, Ctrl+O: Newline (split block)
• Ctrl+T (OSX): Transpose characters

Undo/Redo

• Cmd+Z: Undo
• Shift+Cmd+Z: Redo
• Ctrl+Y (Windows): Redo

Cut/Paste

• Ctrl+K (non-Windows): Cut to secondary clipboard
• Ctrl+Y (non-Windows): Paste from secondary clipboard

Focus

Load an example editor.

• Click into empty editor. Verify that it obtains focus correctly.
• Test clicks on placeholder and edges of editor. Verify same.
• Add text. Repeat with clicks on text.
• Click outside of editor. Verify that it no longer has focus.
• Use tabs to tab into and out of editor. Verify that it obtains and loses focus properly.

Cursor/Selection

For cursor/selection testing, it is recommended that you use the console to observe editorState.getSelection().toJS() to verify that selection changes are being tracked appropriately by the EditorState.

In each test case below, verify valid and correct SelectionState for each. Additionally, DOM selection errors must be repaired.

Navigation/Selection Basics

Load an editor, add some text.

• Simple cursor movement
  • Place cursor within text, use arrow keys to navigate left and right.
  • Navigate up and down, including across blocks.
• Non-collapsed selection with keys
  • Place cursor within text, use arrow keys plus Shift to select multiple characters.
  • Repeat with up/down, and across blocks.
• Non-collapsed selection with mouse
  • Use mouse to drag across editor and select multiple characters.
  • Use mouse to drag and select multiple lines.
• Backward selection
  • Use keyboard and mouse to select “backward”. Verify that the SelectionState appropriately tracks the direction of the selection.

Mouse shortcuts

• Double-click
  • Use double-click to select an entire word.
• Triple-click
  • Use triple-click to select an entire block of text.

Cut/Copy/Paste

Internal Source

Cut

• Select a range of text, use cut command to remove it. Verify that the range is removed properly, and that you can continue to use the editor normally afterward.
• Paste the text back into the editor. Verify that it is inserted properly.
• Repeat with cuts to styled ranges of text, including ranges that contain entities. Verify same.
• Repeat with cuts to ranges that occupy multiple blocks of text. Verify same.
• Repeat with cuts to ranges that occupy custom block components. Verify same.

Copy

• Select a range of text, use copy command.
• Paste the text into the editor. Verify that it is inserted properly, and that you can continue to use the editor normally afterward.
• Open another browser tab with a textarea/ContentEditable, or another editor application. Verify that you your copied content is inserted into the target input.

External Source

Copy content from a source editor, e.g. Quip, Google Docs, Word.

• Focus editor, paste content. Verify that contents are inserted properly. Note: different source editors provide very different HTML structures, so the pasted result may vary broadly.
• Paste content into editor using plaintext-only paste. In OSX, this is accomplished with Cmd+Shift+V. Verify that plaintext is pasted into the editor properly.

Drag/Drop

Internal

• Select a range of text, then use drag/drop to relocate it within the editor. Verify that all text and styles are removed and inserted appropriately.
• Repeat with a selection range that spans multiple lines.
• Repeat with a selection range that includes a custom block component.

External

• Select text from the browser or another application and drag it into the editor. Verify that it is inserted successfully.

IME

The Facebook user base uses dozens of different languages, many of which involve alternative input methods (IME) for text entry. For this reason, changes to input handling code within Draft.js is not always a straightforward matter of managing key events.

For contributors making changes within /handlers/composition, you must perform manual IME tests. For changes within /handlers/edit, it is strongly recommended that you perform manual IME tests.

How to test

On OSX, use Keyboard Preferences to add new languages to your keyboard setup. On Windows, you can use “Add a language” to add new IME types.

Load an editor in your browser and switch to your test language.

Text entry

• Focus the editor, begin typing test string. Carefully verify correct visual input.
• In some languages, you will need to confirm a composed string in order to “commit” that string to the editor.
• Verify that the model updates accordingly.

IME cancellation

• Focus the editor, begin typing test string. Verify correct visual input.
• After typing several characters, use backspace to remove those characters.
• After deletion, verify that the model does not include the typed characters.

Sample Test Strings

• Katakana (Japanese)
  • type: nekutai
  • output: ネクタイ
• Korean
  • type: dkssudgktpdy
  • output: 안녕하세요
• Telex (Vietnamese)
  • type: nawngj
  • output: nặng
• Pinyin - Simplified (Chinese)
  • type: ni hao
  • output: 你好
• More examples welcome!

Text Direction and Alignment

Draft.js provides built-in LTR/RTL alignment behavior. If you are make changes to attributes or styles related to text alignment, you must test typing in an RTL language (e.g. Arabic, Hebrew) to verify that behavior remains correct.

Load an example editor.

• Add LTR text, press return.
• Add RTL text. Verify that the text aligns to the right correctly, leaving the LTR paragraph unaffected.
• Press return. Verify that the cursor remains RTL.
• Add LTR text. Verify that the cursor returns to the left side, with the previous LTR and RTL paragraphs unaffected.
• Add neutral direction characters (e.g. numbers).
  • Add an RTL character. Verify that text is aligned to the right.
  • Remove RTL character, add LTR character. Verify that text is aligned to the left.

Spellcheck and Autocorrect

Spellecheck behavior is slightly different across browsers and platforms, and is handled in Draft.js by waiting for the event to occur within the DOM. The result is that DOM and selection behavior can be a little unpredictable.

Thus, if you are making changes to input event handling code, you should be extremely thorough to test spellcheck handling across browsers.

Spellcheck

Type a misspelled word in the editor.

• Right click it, verify that it is selected and that a spelling correction suggestion is shown in the context menu.
• Choose a suggestion, verify that the corrected word is swapped in for the incorrect word.
• Verify that the cursor selection is in a sensible place, with the inserted word completely selected or with the caret placed after it.
• Undo the spellcheck, verify that the misspelled word is put back in place, with the cursor again in a sensible position.
• Redo the spellcheck, verify that the correctly spelled word is put back in place, with the cursor again in a sensible position.

Autocorrect (iOS, OSX Safari)

On OSX, enable autocorrect via Keyboard preferences, under the “Text” submenu.

Type a misspelled word in the editor, continue typing your sentence.

• Verify that the new word is swapped in properly, and that the cursor is in a sensible position afterward.
• Verify that your continued typing is not adversely affected by the autocorrection.
• Undo the autocorrection, verify that the misspelled word is put back in place, and that the cursor is in a sensible position afterward.