org.scalatest.exceptions.StackDepth.scala Maven / Gradle / Ivy
/*
* Copyright 2001-2013 Artima, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.scalatest.exceptions
import org.scalactic.source
/**
* Trait that encapsulates the information required of an exception thrown by ScalaTest's assertions
* and matchers, which includes a stack depth at which the failing line of test code resides.
*
*
* This trait exists so that it can be mixed into two exception superclasses, StackDepthException,
* from which extend several exceptions that do not depend on JUnit, and JUnitTestFailedError, which
* does depend on JUnit. The latter, which requires JUnit be in the classpath, ensures failed ScalaTest assertions are
* reported as "failures," not "errors," by JUnit.
*
*/
trait StackDepth { this: Throwable =>
/**
* An optional detail message for this StackDepth exception.
*/
val message: Option[String]
/**
* An optional cause, the Throwable that caused this StackDepth exception to be thrown.
*/
val cause: Option[Throwable]
/**
* The depth in the stack trace of this exception at which the line of test code that failed resides.
*/
val failedCodeStackDepth: Int
/**
* A string that provides the full pathname of the source file containing the line of code that failed, suitable
* for presenting to a user.
*
* @return a string containing the full pathname of the source file containing the line of code that caused this exception
*/
val failedCodeFilePathname: Option[String]
/**
* An optional source position describing the line of test code that caused this exception.
*/
val position: Option[source.Position]
/**
* A string that provides the filename and line number of the line of code that failed, suitable
* for presenting to a user of the failing line. It calls failedCodeFileName and
* failedCodeLineNumber to get the failing filename and line number.
*
*
* failedCodeFileName and failedCodeLineNumber will fall back to exception stack trace
* when Position is not avaiable, this is the reason it is a def instead of a val,
* because exceptions are mutable: their stack trace can be changed after the exception is created. This is done, for example,
* by the SeveredStackTraces trait.
*
*
* @return a user-presentable string containing the filename and line number that caused the failed test
*/
def failedCodeFileNameAndLineNumberString: Option[String] = {
for (fileName <- failedCodeFileName; lineNum <- failedCodeLineNumber) yield
fileName + ":" + lineNum
}
/**
* A string that provides the absolute filename and line number of the line of code that failed, suitable
* for presenting to a user of the failing line. It calls failedCodeFilePathname and
* failedCodeLineNumber to get the failing absolute filename and line number.
*
* @return a user-presentable string containing the absolute filename and line number that caused the failed test
*/
lazy val failedCodeFilePathnameAndLineNumberString: Option[String] = {
for (fileName <- failedCodeFilePathname; lineNum <- failedCodeLineNumber) yield
fileName + ":" + lineNum
}
private def stackTraceElement: Option[StackTraceElement] = {
val stackTrace = getStackTrace()
position match {
case Some(pos) => stackTrace.find(e => StackDepthExceptionHelper.isMatch(e, pos))
case None =>
if (stackTrace.length <= failedCodeStackDepth) None
else Some(stackTrace(failedCodeStackDepth))
}
}
/**
* A string that provides the filename of the line of code that failed, suitable
* for presenting to a user, which is taken from this exception's StackTraceElement at the depth specified
* by failedCodeStackDepth.
*
*
* This is a def instead of a val because exceptions are mutable: their stack trace can
* be changed after the exception is created. This is done, for example, by the SeveredStackTraces trait.
*
*
* @return a string containing the filename that caused the failed test
*/
def failedCodeFileName: Option[String] = {
position match {
case Some(pos) => Some(pos.fileName)
case None =>
stackTraceElement flatMap { ele =>
StackDepthExceptionHelper.getFailedCodeFileName(ele)
}
}
}
/**
* A string that provides the line number of the line of code that failed, suitable
* for presenting to a user, which is taken from this exception's StackTraceElement at the depth specified
* by failedCodeStackDepth.
*
*
* This is a def instead of a val because exceptions are mutable: their stack trace can
* be changed after the exception is created. This is done, for example, by the SeveredStackTraces trait.
*
*
* @return a string containing the line number that caused the failed test
*/
def failedCodeLineNumber: Option[Int] = {
position match {
case Some(pos) => Some(pos.lineNumber)
case None =>
stackTraceElement flatMap { ele =>
val lineNum = ele.getLineNumber
if (lineNum > 0) Some(lineNum) else None
}
}
}
/**
* Returns an exception of the same class with failedExceptionStackDepth set to 0 and
* all frames above this stack depth severed off. This can be useful when working with tools (such as IDEs) that do not
* directly support ScalaTest. (Tools that directly support ScalaTest can use the stack depth information delivered
* in the StackDepth exceptions.)
*/
def severedAtStackDepth: Throwable with StackDepth
}