Improve ert-play-keys documentation.

doc/misc/ert.texi

@@ -1132,6 +1132,12 @@ This has the same effect as combining @code{ert-with-test-buffer} with
   (ert-with-test-buffer (:name "global" :selected t)
     @dots{}))
 @end lisp
+
+@findex ert-play-keys
+The @var{select-form} shall be set non-nil when @var{body} contains some
+call to @code{ert-play-keys} to generate programmatically user input
+events inserting text into the test buffer, or starting commands acting
+on the test buffer.
 @end defmac
 
 @defmac ert-with-buffer-selected (buffer &body body)
@@ -1154,6 +1160,13 @@ value is the last form in @var{body}.  Example:
 @end lisp
 
 This displays a temporary buffer like @file{ *temp*-739785*}.
+
+@findex ert-play-keys
+One of the use of @code{ert-with-buffer-selected} is to set the buffer
+to which user input events generated programmatically by one or more
+calls to @code{ert-play-keys} are targetted, which is needed when those
+events are supposed to insert text into this buffer, or start commands
+acting on it.
 @end defmac
 
 @subsection Protecting buffers
@@ -1362,8 +1375,65 @@ vector.  Examples:
 (ert-simulate-keys (kbd "#fake C-m C-a C-k C-m") @dots{})
 (ert-simulate-keys [?b ?2 return] @dots{})
 @end lisp
+
+@findex ert-play-keys
+To generate input event for inserting some text into a buffer, or
+calling some interactive command, see rather function
+@code{ert-play-keys}.
 @end defmac
 
+@defun ert-play-keys (keys)
+Generate programmatically user input events.
+
+@findex ert-simulate-keys
+Contrary to @code{ert-simulate-keys} these events are not intended to be
+consumed by functions reading input, like @code{read-from-minibuffer},
+but are consumed by the command loop which typically will process them
+to start interactive commands or insert text into the selected buffer.
+
+So, before calling @code{ert-play-keys} you generally need to select the
+buffer to which input events are intended to insert text or call a
+command. Do this by passing a non-nil @code{:selected} flag to
+@code{ert-with-test-buffer} if the buffer was created this way, or use
+the @code{ert-with-buffer-selected} macro.
+
+In this example a test buffer is created and selected, then
+@code{ert-play-keys} sets the mark, inserts text @samp{n'importe quoi}
+and kills it, then the test checks that the killed text is in the kill
+ring and the test buffer is empty, then a second @code{ert-play-keys}
+call yanks again the killed text, and finally the test checks the test
+buffer contains @samp{n'importe quoi}:
+
+@example
+(ert-deftest ert-example-kill&yank ()
+  "Test kill and yank."
+  (ert-with-test-buffer (:selected t)
+    (ert-play-keys "C-SPC n'importe SPC quoi C-w")
+    (should (string= "n'importe quoi" (car kill-ring)))
+    (should (string= "" (buffer-substring (point-min) (point-max))))
+    (ert-play-keys "C-y")
+    (should (string= "n'importe quoi"
+                     (buffer-substring (point-min) (point-max))))))
+@end example
+
+@noindent
+Write input events as above with a string in the input format used by
+@code{key-parse}, or directly in the internal Emacs representation like
+here which is otherwise the same test as above:
+
+@example
+(ert-deftest ert-example-kill&yank ()
+  "Test kill and yank."
+  (ert-with-test-buffer (:selected t)
+    (ert-play-keys (vconcat [ ?\C- ] "n'importe quoi" [ ?\C-w]))
+    (should (string= "n'importe quoi" (car kill-ring)))
+    (should (string= "" (buffer-substring (point-min) (point-max))))
+    (ert-play-keys [ ?\C-y ])
+    (should (string= "n'importe quoi"
+                     (buffer-substring (point-min) (point-max))))))
+@end example
+@end defun
+
 @defun ert-filter-string (s &rest regexps)
 This function returns a copy of string @var{s} with all matches of
 @var{regexps} removed.  Elements of @var{regexps} may also be

lisp/emacs-lisp/ert-x.el

@@ -422,8 +422,9 @@ The same keyword arguments are supported as in
 KEYS shall have the same format as in a call to function `kmacro'.
 
 This macro should be expanded within the body of
-`ert-with-display-current-buffer' when the keys KEYS start commands
-acting on the current buffer."
+`ert-with-buffer-selected' to select a buffer when keys KEYS start
+commands acting on this buffer, or within the body of
+`ert-with-test-buffer' used with `:selected' flag set."
   (funcall
     (kmacro keys)))