1 // ***********************************************************************
2 // Copyright (c) 2009 Charlie Poole
3 //
4 // Permission is hereby granted, free of charge, to any person obtaining
5 // a copy of this software and associated documentation files (the
6 // "Software"), to deal in the Software without restriction, including
7 // without limitation the rights to use, copy, modify, merge, publish,
8 // distribute, sublicense, and/or sell copies of the Software, and to
9 // permit persons to whom the Software is furnished to do so, subject to
10 // the following conditions:
11 //
12 // The above copyright notice and this permission notice shall be
13 // included in all copies or substantial portions of the Software.
14 //
15 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
19 // LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
20 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
21 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 // ***********************************************************************
23 
24 using System;
25 using System.ComponentModel;
26 using NUnit.Framework.Constraints;
27 using NUnit.Framework.Internal;
28 
29 namespace NUnit.Framework
30 {
31     /// <summary>
32     /// Provides static methods to express the assumptions
33     /// that must be met for a test to give a meaningful
34     /// result. If an assumption is not met, the test
35     /// should produce an inconclusive result.
36     /// </summary>
37     public class Assume
38     {
39         #region Equals and ReferenceEquals
40 
41         /// <summary>
42         /// The Equals method throws an AssertionException. This is done
43         /// to make sure there is no mistake by calling this function.
44         /// </summary>
45         /// <param name="a"></param>
46         /// <param name="b"></param>
47         [EditorBrowsable(EditorBrowsableState.Never)]
Equals(object a, object b)48         public static new bool Equals(object a, object b)
49         {
50             // TODO: This should probably be InvalidOperationException
51             throw new AssertionException("Assert.Equals should not be used for Assertions");
52         }
53 
54         /// <summary>
55         /// override the default ReferenceEquals to throw an AssertionException. This
56         /// implementation makes sure there is no mistake in calling this function
57         /// as part of Assert.
58         /// </summary>
59         /// <param name="a"></param>
60         /// <param name="b"></param>
ReferenceEquals(object a, object b)61         public static new void ReferenceEquals(object a, object b)
62         {
63             throw new AssertionException("Assert.ReferenceEquals should not be used for Assertions");
64         }
65 
66         #endregion
67 
68         #region Assume.That
69 
70         #region Object
71 
72         /// <summary>
73         /// Apply a constraint to an actual value, succeeding if the constraint
74         /// is satisfied and throwing an InconclusiveException on failure.
75         /// </summary>
76         /// <param name="expression">A Constraint expression to be applied</param>
77         /// <param name="actual">The actual value to test</param>
That(object actual, IResolveConstraint expression)78         static public void That(object actual, IResolveConstraint expression)
79         {
80             Assume.That(actual, expression, null, null);
81         }
82 
83         /// <summary>
84         /// Apply a constraint to an actual value, succeeding if the constraint
85         /// is satisfied and throwing an InconclusiveException on failure.
86         /// </summary>
87         /// <param name="expression">A Constraint expression to be applied</param>
88         /// <param name="actual">The actual value to test</param>
89         /// <param name="message">The message that will be displayed on failure</param>
That(object actual, IResolveConstraint expression, string message)90         static public void That(object actual, IResolveConstraint expression, string message)
91         {
92             Assume.That(actual, expression, message, null);
93         }
94 
95         /// <summary>
96         /// Apply a constraint to an actual value, succeeding if the constraint
97         /// is satisfied and throwing an InconclusiveException on failure.
98         /// </summary>
99         /// <param name="expression">A Constraint expression to be applied</param>
100         /// <param name="actual">The actual value to test</param>
101         /// <param name="message">The message that will be displayed on failure</param>
102         /// <param name="args">Arguments to be used in formatting the message</param>
That(object actual, IResolveConstraint expression, string message, params object[] args)103         static public void That(object actual, IResolveConstraint expression, string message, params object[] args)
104         {
105             Constraint constraint = expression.Resolve();
106 
107             if (!constraint.Matches(actual))
108             {
109                 MessageWriter writer = new TextMessageWriter(message, args);
110                 constraint.WriteMessageTo(writer);
111                 throw new InconclusiveException(writer.ToString());
112             }
113         }
114         #endregion
115 
116         #region Boolean
117 
118         /// <summary>
119         /// Asserts that a condition is true. If the condition is false the method throws
120         /// an <see cref="InconclusiveException"/>.
121         /// </summary>
122         /// <param name="condition">The evaluated condition</param>
123         /// <param name="message">The message to display if the condition is false</param>
124         /// <param name="args">Arguments to be used in formatting the message</param>
That(bool condition, string message, params object[] args)125         static public void That(bool condition, string message, params object[] args)
126         {
127             Assume.That(condition, Is.True, message, args);
128         }
129 
130         /// <summary>
131         /// Asserts that a condition is true. If the condition is false the method throws
132         /// an <see cref="InconclusiveException"/>.
133         /// </summary>
134         /// <param name="condition">The evaluated condition</param>
135         /// <param name="message">The message to display if the condition is false</param>
That(bool condition, string message)136         static public void That(bool condition, string message)
137         {
138             Assume.That(condition, Is.True, message, null);
139         }
140 
141         /// <summary>
142         /// Asserts that a condition is true. If the condition is false the
143         /// method throws an <see cref="InconclusiveException"/>.
144         /// </summary>
145         /// <param name="condition">The evaluated condition</param>
That(bool condition)146         static public void That(bool condition)
147         {
148             Assume.That(condition, Is.True, null, null);
149         }
150 
151         #endregion
152 
153         #region ref Boolean
154 
155 #if !CLR_2_0 && !CLR_4_0
156         /// <summary>
157         /// Apply a constraint to a referenced boolean, succeeding if the constraint
158         /// is satisfied and throwing an InconclusiveException on failure.
159         /// </summary>
160         /// <param name="expression">A Constraint expression to be applied</param>
161         /// <param name="actual">The actual value to test</param>
That(ref bool actual, IResolveConstraint expression)162         static public void That(ref bool actual, IResolveConstraint expression)
163         {
164             Assume.That(ref actual, expression.Resolve(), null, null);
165         }
166 
167         /// <summary>
168         /// Apply a constraint to a referenced boolean, succeeding if the constraint
169         /// is satisfied and throwing an InconclusiveException on failure.
170         /// </summary>
171         /// <param name="expression">A Constraint expression to be applied</param>
172         /// <param name="actual">The actual value to test</param>
173         /// <param name="message">The message that will be displayed on failure</param>
That(ref bool actual, IResolveConstraint expression, string message)174         static public void That(ref bool actual, IResolveConstraint expression, string message)
175         {
176             Assume.That(ref actual, expression.Resolve(), message, null);
177         }
178 
179         /// <summary>
180         /// Apply a constraint to a referenced boolean, succeeding if the constraint
181         /// is satisfied and throwing an InconclusiveException on failure.
182         /// </summary>
183         /// <param name="actual">The actual value to test</param>
184         /// <param name="expression">A Constraint expression to be applied</param>
185         /// <param name="message">The message that will be displayed on failure</param>
186         /// <param name="args">Arguments to be used in formatting the message</param>
That(ref bool actual, IResolveConstraint expression, string message, params object[] args)187         static public void That(ref bool actual, IResolveConstraint expression, string message, params object[] args)
188         {
189             Constraint constraint = expression.Resolve();
190 
191             if (!constraint.Matches(ref actual))
192             {
193                 MessageWriter writer = new TextMessageWriter(message, args);
194                 constraint.WriteMessageTo(writer);
195                 throw new InconclusiveException(writer.ToString());
196             }
197         }
198 #endif
199 
200         #endregion
201 
202         #region ActualValueDelegate
203 
204 #if CLR_2_0 || CLR_4_0
205         /// <summary>
206         /// Apply a constraint to an actual value, succeeding if the constraint
207         /// is satisfied and throwing an InconclusiveException on failure.
208         /// </summary>
209         /// <param name="expr">A Constraint expression to be applied</param>
210         /// <param name="del">An ActualValueDelegate returning the value to be tested</param>
That(ActualValueDelegate<T> del, IResolveConstraint expr)211         static public void That<T>(ActualValueDelegate<T> del, IResolveConstraint expr)
212         {
213             Assume.That(del, expr.Resolve(), null, null);
214         }
215 
216         /// <summary>
217         /// Apply a constraint to an actual value, succeeding if the constraint
218         /// is satisfied and throwing an InconclusiveException on failure.
219         /// </summary>
220         /// <param name="expr">A Constraint expression to be applied</param>
221         /// <param name="del">An ActualValueDelegate returning the value to be tested</param>
222         /// <param name="message">The message that will be displayed on failure</param>
That(ActualValueDelegate<T> del, IResolveConstraint expr, string message)223         static public void That<T>(ActualValueDelegate<T> del, IResolveConstraint expr, string message)
224         {
225             Assume.That(del, expr.Resolve(), message, null);
226         }
227 
228         /// <summary>
229         /// Apply a constraint to an actual value, succeeding if the constraint
230         /// is satisfied and throwing an InconclusiveException on failure.
231         /// </summary>
232         /// <param name="del">An ActualValueDelegate returning the value to be tested</param>
233         /// <param name="expr">A Constraint expression to be applied</param>
234         /// <param name="message">The message that will be displayed on failure</param>
235         /// <param name="args">Arguments to be used in formatting the message</param>
That(ActualValueDelegate<T> del, IResolveConstraint expr, string message, params object[] args)236         static public void That<T>(ActualValueDelegate<T> del, IResolveConstraint expr, string message, params object[] args)
237         {
238             Constraint constraint = expr.Resolve();
239 
240             if (!constraint.Matches(del))
241             {
242                 MessageWriter writer = new TextMessageWriter(message, args);
243                 constraint.WriteMessageTo(writer);
244                 throw new InconclusiveException(writer.ToString());
245             }
246         }
247 #else
248         /// <summary>
249         /// Apply a constraint to an actual value, succeeding if the constraint
250         /// is satisfied and throwing an InconclusiveException on failure.
251         /// </summary>
252         /// <param name="expr">A Constraint expression to be applied</param>
253         /// <param name="del">An ActualValueDelegate returning the value to be tested</param>
That(ActualValueDelegate del, IResolveConstraint expr)254         static public void That(ActualValueDelegate del, IResolveConstraint expr)
255         {
256             Assume.That(del, expr.Resolve(), null, null);
257         }
258 
259         /// <summary>
260         /// Apply a constraint to an actual value, succeeding if the constraint
261         /// is satisfied and throwing an InconclusiveException on failure.
262         /// </summary>
263         /// <param name="expr">A Constraint expression to be applied</param>
264         /// <param name="del">An ActualValueDelegate returning the value to be tested</param>
265         /// <param name="message">The message that will be displayed on failure</param>
That(ActualValueDelegate del, IResolveConstraint expr, string message)266         static public void That(ActualValueDelegate del, IResolveConstraint expr, string message)
267         {
268             Assume.That(del, expr.Resolve(), message, null);
269         }
270 
271         /// <summary>
272         /// Apply a constraint to an actual value, succeeding if the constraint
273         /// is satisfied and throwing an InconclusiveException on failure.
274         /// </summary>
275         /// <param name="del">An ActualValueDelegate returning the value to be tested</param>
276         /// <param name="expr">A Constraint expression to be applied</param>
277         /// <param name="message">The message that will be displayed on failure</param>
278         /// <param name="args">Arguments to be used in formatting the message</param>
That(ActualValueDelegate del, IResolveConstraint expr, string message, params object[] args)279         static public void That(ActualValueDelegate del, IResolveConstraint expr, string message, params object[] args)
280         {
281             Constraint constraint = expr.Resolve();
282 
283            if (!constraint.Matches(del))
284             {
285                 MessageWriter writer = new TextMessageWriter(message, args);
286                 constraint.WriteMessageTo(writer);
287                 throw new InconclusiveException(writer.ToString());
288             }
289         }
290 #endif
291 
292         #endregion
293 
294         #region ref Object
295 
296 #if CLR_2_0 || CLR_4_0
297         /// <summary>
298         /// Apply a constraint to a referenced value, succeeding if the constraint
299         /// is satisfied and throwing an InconclusiveException on failure.
300         /// </summary>
301         /// <param name="expression">A Constraint expression to be applied</param>
302         /// <param name="actual">The actual value to test</param>
That(ref T actual, IResolveConstraint expression)303         static public void That<T>(ref T actual, IResolveConstraint expression)
304         {
305             Assume.That(ref actual, expression.Resolve(), null, null);
306         }
307 
308         /// <summary>
309         /// Apply a constraint to a referenced value, succeeding if the constraint
310         /// is satisfied and throwing an InconclusiveException on failure.
311         /// </summary>
312         /// <param name="expression">A Constraint expression to be applied</param>
313         /// <param name="actual">The actual value to test</param>
314         /// <param name="message">The message that will be displayed on failure</param>
That(ref T actual, IResolveConstraint expression, string message)315         static public void That<T>(ref T actual, IResolveConstraint expression, string message)
316         {
317             Assume.That(ref actual, expression.Resolve(), message, null);
318         }
319 
320         /// <summary>
321         /// Apply a constraint to a referenced value, succeeding if the constraint
322         /// is satisfied and throwing an InconclusiveException on failure.
323         /// </summary>
324         /// <param name="expression">A Constraint expression to be applied</param>
325         /// <param name="actual">The actual value to test</param>
326         /// <param name="message">The message that will be displayed on failure</param>
327         /// <param name="args">Arguments to be used in formatting the message</param>
That(ref T actual, IResolveConstraint expression, string message, params object[] args)328         static public void That<T>(ref T actual, IResolveConstraint expression, string message, params object[] args)
329         {
330             Constraint constraint = expression.Resolve();
331 
332             if (!constraint.Matches(ref actual))
333             {
334                 MessageWriter writer = new TextMessageWriter(message, args);
335                 constraint.WriteMessageTo(writer);
336                 throw new InconclusiveException(writer.ToString());
337             }
338         }
339 #endif
340 
341         #endregion
342 
343         #region TestDelegate
344 
345         /// <summary>
346         /// Asserts that the code represented by a delegate throws an exception
347         /// that satisfies the constraint provided.
348         /// </summary>
349         /// <param name="code">A TestDelegate to be executed</param>
350         /// <param name="constraint">A ThrowsConstraint used in the test</param>
That(TestDelegate code, IResolveConstraint constraint)351         static public void That(TestDelegate code, IResolveConstraint constraint)
352         {
353             Assume.That((object)code, constraint);
354         }
355 
356         #endregion
357 
358         #endregion
359     }
360 }
361