--[[
	Create a new TestPlan from a list of specification functions.

	These functions should call a combination of `describe` and `it` (and their
	variants), which will be turned into a test plan to be executed.

	Parameters:
		- modulesList - list of tables describing test modules {
			method, -- specification function described above
			path, -- array of parent entires, first element is the leaf that owns `method`
			pathStringForSorting -- a string representation of `path`, used for sorting of the test plan
		}
		- planArgs - table of additional plan params {
			runTestsByPath - Runs only tests with these exact paths
			testNamePattern - Only tests matching this Lua pattern string will run. Pass empty or nil to run all tests
			testPathPattern - Only tests paths matching this pattern will run
			testPathIgnorePatterns - Only tests paths that do not match this pattern will run
			extraEnvironment - Lua table holding additional functions and variables to be injected into the specification
								function during execution
		}
]]

function TestPlanner.createPlan(modulesList, planArgs)
	local testPlanArgs
	if type(planArgs) == "string" then
		testPlanArgs = { testNamePattern = planArgs }
	else
		testPlanArgs = planArgs
	end

	local plan = TestPlan.new(testPlanArgs)

	table.sort(modulesList, function(a, b)
		return a.pathStringForSorting < b.pathStringForSorting
	end)

	for _, module in ipairs(modulesList) do
		plan:addRoot(module.path, module.method, module.instance)
	end

	return plan
end

return TestPlanner
