@rbxts/specium 1.0.0 → 1.1.0

package/lib/index.d.ts

@@ -7,6 +7,7 @@ interface SpeciumRunResult {
   total: number;
   passed: number;
   failed: number;
+  skipped: number;
   suites: SpeciumSuiteResult[];
 }
 
@@ -25,6 +26,10 @@ interface SpeciumTestResult {
 interface SpeciumSuiteContext {
   it(name: string, fn: () => SpeciumResult | void): void;
   describe(name: string, fn: (ctx: SpeciumSuiteContext) => void): void;
+  beforeAll(fn: () => void): void;
+  afterAll(fn: () => void): void;
+  beforeEach(fn: () => void): void;
+  afterEach(fn: () => void): void;
 }
 
 interface SpeciumSuite {
@@ -54,9 +59,7 @@ interface SpeciumMatchers extends SpeciumMatchersRaw {
 interface Specium {
   suite(name: string, fn: (ctx: SpeciumSuiteContext) => void): SpeciumSuite;
   run(suite: SpeciumSuite): [string, SpeciumRunResult];
-  runTests(
-    testsFolder: Instance | Instance[],
-  ): [string, Array<SpeciumRunResult>];
+  runTests(testsFolder: Instance | Instance[]): [string, SpeciumRunResult[]];
   expect(received: unknown): SpeciumMatchers;
   success(message: string): SpeciumResult;
   error(message: string): SpeciumResult;

package/lib/init.luau

@@ -10,15 +10,21 @@ local Specium = {}
 type SpeciumTest = {
 	name: string,
 	fn: () -> SpeciumResult,
+	skipped: boolean,
 }
 type SpeciumSuite = {
 	name: string,
 	tests: { SpeciumTest },
 	subSuites: { SpeciumSuite },
+	beforeAll: (() -> ())?,
+	afterAll: (() -> ())?,
+	beforeEach: (() -> ())?,
+	afterEach: (() -> ())?,
 }
 type SpeciumTestResult = {
 	name: string,
 	success: boolean,
+	skipped: boolean,
 	message: string,
 }
 type SpeciumSuiteResult = {
@@ -48,17 +54,28 @@ export type SpeciumRunResult = {
 	total: number,
 	passed: number,
 	failed: number,
+	skipped: number,
 	suites: { SpeciumSuiteResult },
 }
 --[=[
 	@interface SpeciumSuiteContext
 	@within Specium
 	.it (name: string, fn: () -> SpeciumResult) -> () -- Registers a test case inside the current suite
+	.skip (name: string, fn () -> SpeciumResult) -> () -- Registers a test case that will be skipped when the suite runs
 	.describe (name: string, fn: (SpeciumSuiteContext) -> ()) -> () -- Creates a nested sub-suite
+	.beforeAll (() -> ())? -- Runs once before all tests in the suite
+	.afterAll (() -> ())? -- Runs once after all tests in the suite
+	.beforeEach (() -> ())? -- Runs before each test in the suite
+	.afterEach (() -> ())? -- Runs after each test in the suite
 ]=]
 export type SpeciumSuiteContext = {
 	it: (name: string, fn: () -> SpeciumResult) -> (),
+	skip: (name: string, fn: () -> SpeciumResult) -> (),
 	describe: (name: string, fn: (SpeciumSuiteContext) -> ()) -> (),
+	beforeAll: (() -> ()) -> (),
+	afterAll: (() -> ()) -> (),
+	beforeEach: (() -> ()) -> (),
+	afterEach: (() -> ()) -> (),
 }
 
 --[=[
@@ -100,6 +117,15 @@ function Specium.suite(name: string, fn: (SpeciumSuiteContext) -> ()): SpeciumSu
 			table.insert(currentSuite.tests, {
 				name = name,
 				fn = fn,
+				skipped = false,
+			})
+		end
+
+		function ctx.skip(name: string, fn: () -> SpeciumResult)
+			table.insert(currentSuite.tests, {
+				name = name,
+				fn = fn,
+				skipped = true,
 			})
 		end
 
@@ -115,6 +141,17 @@ function Specium.suite(name: string, fn: (SpeciumSuiteContext) -> ()): SpeciumSu
 			fn(createContext(newSuite))
 		end
 
+		local function createSuiteSetter(key: string)
+			ctx[key] = function(value: any)
+				currentSuite[key] = value
+			end
+		end
+
+		createSuiteSetter("beforeAll")
+		createSuiteSetter("afterAll")
+		createSuiteSetter("beforeEach")
+		createSuiteSetter("afterEach")
+
 		return ctx
 	end
 
@@ -147,6 +184,7 @@ end
 function Specium.run(suite: SpeciumSuite): (string, SpeciumRunResult)
 	local total = 0
 	local passed = 0
+	local skipped = 0
 
 	local output = "\n"
 
@@ -154,6 +192,7 @@ function Specium.run(suite: SpeciumSuite): (string, SpeciumRunResult)
 		total = 0,
 		passed = 0,
 		failed = 0,
+		skipped = 0,
 		suites = {},
 	}
 
@@ -169,10 +208,40 @@ function Specium.run(suite: SpeciumSuite): (string, SpeciumRunResult)
 
 		output ..= `{string.rep(" ", depth - 1)}> {currentSuite.name}\n`
 
+		local function opcall(fn: (() -> ())?, hookName: string)
+			if not fn then
+				return
+			end
+
+			local ok, err = xpcall(fn, function(e)
+				return `{e}\n{debug.traceback()}`
+			end)
+
+			if not ok then
+				warn(`[Specium] {hookName} failed in "{currentSuite.name}": {err}`)
+			end
+		end
+
+		opcall(currentSuite.beforeAll, "beforeAll")
+
 		for _, test in currentSuite.tests do
 			total += 1
 
+			if test.skipped then
+				skipped += 1
+				output ..= `{indent}[Skip] {test.name}\n`
+				table.insert(suiteResult.tests, {
+					name = test.name,
+					success = false,
+					message = "skipped",
+					skipped = true,
+				})
+				continue
+			end
+
+			opcall(currentSuite.beforeEach, "beforeEach")
 			local ok, result = pcall(test.fn)
+			opcall(currentSuite.afterEach, "afterEach")
 
 			if not ok then
 				result = Specium.error(tostring(result))
@@ -191,6 +260,7 @@ function Specium.run(suite: SpeciumSuite): (string, SpeciumRunResult)
 				name = test.name,
 				success = result.success,
 				message = result.message,
+				skipped = false,
 			})
 		end
 
@@ -199,6 +269,8 @@ function Specium.run(suite: SpeciumSuite): (string, SpeciumRunResult)
 			table.insert(suiteResult.subSuites, subResult)
 		end
 
+		opcall(currentSuite.afterAll, "afterAll")
+
 		return suiteResult
 	end
 
@@ -206,11 +278,26 @@ function Specium.run(suite: SpeciumSuite): (string, SpeciumRunResult)
 
 	results.total = total
 	results.passed = passed
-	results.failed = total - passed
+	results.failed = total - passed - skipped
+	results.skipped = skipped
 	results.suites = { rootResult }
 
 	output ..= "\n\nResult:\n"
-	output ..= total > 0 and `{passed}/{total} ({math.round(passed / total * 1000) / 10}%) tests passed` or "no tests found"
+	if total > 0 then
+		local ran = total - skipped
+		local summary
+		if ran > 0 then
+			summary = `{passed}/{ran} ({math.round(passed / ran * 1000) / 10}%) tests passed`
+		else
+			summary = "all tests skipped"
+		end
+		if skipped > 0 then
+			summary ..= `, {skipped} skipped`
+		end
+		output ..= summary
+	else
+		output ..= "no tests found"
+	end
 
 	return output, results
 end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/specium",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A simple and flexible testing framework for Roblox",
   "main": "lib/init.luau",
   "types": "lib/index.d.ts",