📦 NEW: Add validateOrFail method for validating email (#30)

* 👌 IMPROVE: Ignore new location for.engine directory

* 📦 NEW: Add validateOrFail method for validating email

This makes mail validation easier, so the client does not have to check the mail result and will instead know immediately whether the configured mail is valid.

Author: michaelborn

.gitignore

@@ -4,7 +4,7 @@
 .tmp/**
 
 .env
-test-harness/.engine/**
+.engine
 test-harness/coldbox/**
 test-harness/docbox/**
 test-harness/testbox/**

models/Mail.cfc

@@ -195,6 +195,20 @@ component accessors="true" {
 		);
 	}
 
+	/**
+	 * Run email validation and throw an InvalidMailException if required params are missing.
+	 */
+	Mail function validateOrFail(){
+		if ( NOT this.validate() ){
+			throw(
+				type   : "InvalidMailException",
+				message: "One or more required fields are missing.",
+				detail : "Please check the basic mail fields of To, From, Subject and Body as they are empty. To: #variables.config.to#, From: #variables.config.from#, Subject Len = #variables.config.subject.length()#, Body Len = #variables.config.body.length()#."
+			);
+		}
+		return this;
+	}
+
 	/**
 	 * Validate that the basic fields of from, to, subject, and body are set for sending mail
 	 */

test-harness/tests/specs/MailTest.cfc

@@ -61,6 +61,29 @@
 				expect( mail.validate() ).toBeTrue();
 			} );
 
+			it( "validateOrFail will throw for invalid mail", function() {
+
+				expect(function() {
+					mail.configure(
+						from    = "[email protected]",
+						to      = "[email protected]"
+						// OMIT subject... "Oops! DID I DO THAT???"
+					)
+					.validateOrFail()
+				}).toThrow( "InvalidMailException" );
+			});
+
+			it( "validateOrFail won't throw for valid emails", function() {
+				expect( function() {
+					mail.configure(
+						subject = "Hello",
+						from    = "[email protected]",
+						to      = "[email protected]",
+						body    = "Hello"
+					).validateOrFail();
+				}).notToThrow( "InvalidMailException" );
+			});
+
 			it( "can set html types", function(){
 				mail.configure(
 						subject = "Hello",