cloudstack/tools/mockito/javadoc/org/mockito/ArgumentCaptor.html
2011-03-19 11:46:18 -07:00

398 lines
16 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.5.0_22) on Mon May 24 23:03:13 CEST 2010 -->
<TITLE>
ArgumentCaptor (Mockito API)
</TITLE>
<META NAME="keywords" CONTENT="org.mockito.ArgumentCaptor class">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
parent.document.title="ArgumentCaptor (Mockito API)";
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/ArgumentCaptor.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../org/mockito/Answers.html" title="enum in org.mockito"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../org/mockito/ArgumentMatcher.html" title="class in org.mockito"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../index.html?org/mockito/ArgumentCaptor.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="ArgumentCaptor.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
org.mockito</FONT>
<BR>
Class ArgumentCaptor&lt;T&gt;</H2>
<PRE>
java.lang.Object
<IMG SRC="../../resources/inherit.gif" ALT="extended by "><B>org.mockito.ArgumentCaptor&lt;T&gt;</B>
</PRE>
<HR>
<DL>
<DT><PRE>public class <B>ArgumentCaptor&lt;T&gt;</B><DT>extends java.lang.Object</DL>
</PRE>
<P>
Use it to capture argument values for further assertions.
<p>
Mockito verifies argument values in natural java style: by using an equals() method.
This is also the recommended way of matching arguments because it makes tests clean & simple.
In some situations though, it is helpful to assert on certain arguments after the actual verification.
For example:
<pre>
ArgumentCaptor&lt;Person&gt; argument = ArgumentCaptor.forClass(Person.class);
verify(mock).doSomething(argument.capture());
assertEquals("John", argument.getValue().getName());
</pre>
<p>
<b>Warning:</b> it is recommended to use ArgumentCaptor with verification <b>but not</b> with stubbing.
Using ArgumentCaptor with stubbing may decrease test readability because captor is created outside of assert (aka verify or 'then') block.
Also it may reduce defect localization because if stubbed method was not called then no argument is captured.
<p>
In a way ArgumentCaptor is related to custom argument matchers (see javadoc for <A HREF="../../org/mockito/ArgumentMatcher.html" title="class in org.mockito"><CODE>ArgumentMatcher</CODE></A> class).
Both techniques can be used for making sure certain arguments where passed to mocks.
However, ArgumentCaptor may be a better fit if:
<ul>
<li>custom argument matcher is not likely to be reused</li>
<li>you just need it to assert on argument values to complete verification</li>
</ul>
Custom argument matchers via <A HREF="../../org/mockito/ArgumentMatcher.html" title="class in org.mockito"><CODE>ArgumentMatcher</CODE></A> are usually better for stubbing.
<p>
There is an <b>annotation</b> that you might find useful: &#64;<A HREF="../../org/mockito/Captor.html" title="annotation in org.mockito"><CODE>Captor</CODE></A>
<p>
See the full documentation on Mockito in javadoc for <A HREF="../../org/mockito/Mockito.html" title="class in org.mockito"><CODE>Mockito</CODE></A> class.
<P>
<P>
<HR>
<P>
<!-- ======== CONSTRUCTOR SUMMARY ======== -->
<A NAME="constructor_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Constructor Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><B><A HREF="../../org/mockito/ArgumentCaptor.html#ArgumentCaptor()">ArgumentCaptor</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<B>Deprecated.</B>&nbsp;<I><b>Please use factory method <A HREF="../../org/mockito/ArgumentCaptor.html#forClass(java.lang.Class)"><CODE>forClass(Class)</CODE></A> to create captors</b>
<p>
This is required to avoid NullPointerExceptions when autoUnboxing primitive types.
See issue 99.
<p>
Example:
<pre>
ArgumentCaptor&lt;Person&gt; argument = ArgumentCaptor.forClass(Person.class);
verify(mock).doSomething(argument.capture());
assertEquals("John", argument.getValue().getName());
</pre></I></TD>
</TR>
</TABLE>
&nbsp;
<!-- ========== METHOD SUMMARY =========== -->
<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Method Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;<A HREF="../../org/mockito/ArgumentCaptor.html" title="type parameter in ArgumentCaptor">T</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../org/mockito/ArgumentCaptor.html#capture()">capture</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Use it to capture the argument.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" SUMMARY="">
<TR ALIGN="right" VALIGN="">
<TD NOWRAP><FONT SIZE="-1">
<CODE>&lt;T&gt; <A HREF="../../org/mockito/ArgumentCaptor.html" title="class in org.mockito">ArgumentCaptor</A>&lt;T&gt;</CODE></FONT></TD>
</TR>
</TABLE>
</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../org/mockito/ArgumentCaptor.html#forClass(java.lang.Class)">forClass</A></B>(java.lang.Class&lt;T&gt;&nbsp;clazz)</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;java.util.List&lt;<A HREF="../../org/mockito/ArgumentCaptor.html" title="type parameter in ArgumentCaptor">T</A>&gt;</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../org/mockito/ArgumentCaptor.html#getAllValues()">getAllValues</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns all captured values.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;<A HREF="../../org/mockito/ArgumentCaptor.html" title="type parameter in ArgumentCaptor">T</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../org/mockito/ArgumentCaptor.html#getValue()">getValue</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns the captured value of the argument.</TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TH ALIGN="left"><B>Methods inherited from class java.lang.Object</B></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE>clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</CODE></TD>
</TR>
</TABLE>
&nbsp;
<P>
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<A NAME="constructor_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
<B>Constructor Detail</B></FONT></TH>
</TR>
</TABLE>
<A NAME="ArgumentCaptor()"><!-- --></A><H3>
ArgumentCaptor</H3>
<PRE>
<FONT SIZE="-1">@Deprecated
</FONT>public <B>ArgumentCaptor</B>()</PRE>
<DL>
<DD><B>Deprecated.</B>&nbsp;<I><b>Please use factory method <A HREF="../../org/mockito/ArgumentCaptor.html#forClass(java.lang.Class)"><CODE>forClass(Class)</CODE></A> to create captors</b>
<p>
This is required to avoid NullPointerExceptions when autoUnboxing primitive types.
See issue 99.
<p>
Example:
<pre>
ArgumentCaptor&lt;Person&gt; argument = ArgumentCaptor.forClass(Person.class);
verify(mock).doSomething(argument.capture());
assertEquals("John", argument.getValue().getName());
</pre></I>
<P>
</DL>
<!-- ============ METHOD DETAIL ========== -->
<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
<B>Method Detail</B></FONT></TH>
</TR>
</TABLE>
<A NAME="capture()"><!-- --></A><H3>
capture</H3>
<PRE>
public <A HREF="../../org/mockito/ArgumentCaptor.html" title="type parameter in ArgumentCaptor">T</A> <B>capture</B>()</PRE>
<DL>
<DD>Use it to capture the argument. This method <b>must be used inside of verification</b>.
<p>
Internally, this method registers a special implementation of an <A HREF="../../org/mockito/ArgumentMatcher.html" title="class in org.mockito"><CODE>ArgumentMatcher</CODE></A>.
This argument matcher stores the argument value so that you can use it later to perform assertions.
<p>
See examples in javadoc for <A HREF="../../org/mockito/ArgumentCaptor.html" title="class in org.mockito"><CODE>ArgumentCaptor</CODE></A> class.
<P>
<DD><DL>
<DT><B>Returns:</B><DD>null</DL>
</DD>
</DL>
<HR>
<A NAME="getValue()"><!-- --></A><H3>
getValue</H3>
<PRE>
public <A HREF="../../org/mockito/ArgumentCaptor.html" title="type parameter in ArgumentCaptor">T</A> <B>getValue</B>()</PRE>
<DL>
<DD>Returns the captured value of the argument.
<p>
If the method was called multiple times then it returns the latest captured value
<p>
See examples in javadoc for <A HREF="../../org/mockito/ArgumentCaptor.html" title="class in org.mockito"><CODE>ArgumentCaptor</CODE></A> class.
<P>
<DD><DL>
<DT><B>Returns:</B><DD>captured argument value</DL>
</DD>
</DL>
<HR>
<A NAME="getAllValues()"><!-- --></A><H3>
getAllValues</H3>
<PRE>
public java.util.List&lt;<A HREF="../../org/mockito/ArgumentCaptor.html" title="type parameter in ArgumentCaptor">T</A>&gt; <B>getAllValues</B>()</PRE>
<DL>
<DD>Returns all captured values. Use it in case the verified method was called multiple times.
<p>
Example:
<pre>
ArgumentCaptor&lt;Person&gt; peopleCaptor = ArgumentCaptor.forClass(Person.class);
verify(mock, times(2)).doSomething(peopleCaptor.capture());
List&lt;Person&gt; capturedPeople = peopleCaptor.getAllValues();
assertEquals("John", capturedPeople.get(0).getName());
assertEquals("Jane", capturedPeople.get(1).getName());
</pre>
See more examples in javadoc for <A HREF="../../org/mockito/ArgumentCaptor.html" title="class in org.mockito"><CODE>ArgumentCaptor</CODE></A> class.
<P>
<DD><DL>
<DT><B>Returns:</B><DD>captured argument value</DL>
</DD>
</DL>
<HR>
<A NAME="forClass(java.lang.Class)"><!-- --></A><H3>
forClass</H3>
<PRE>
public static &lt;T&gt; <A HREF="../../org/mockito/ArgumentCaptor.html" title="class in org.mockito">ArgumentCaptor</A>&lt;T&gt; <B>forClass</B>(java.lang.Class&lt;T&gt;&nbsp;clazz)</PRE>
<DL>
<DD><DL>
</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/ArgumentCaptor.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../org/mockito/Answers.html" title="enum in org.mockito"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../org/mockito/ArgumentMatcher.html" title="class in org.mockito"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../index.html?org/mockito/ArgumentCaptor.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="ArgumentCaptor.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
</BODY>
</HTML>