Workspace.Test (Workspace v0.2.1)
View SourceConvenience helper functions for workspace tests.
Summary
Functions
Asserts that the captured cli output matches the expected value with respect to the given options.
Creates a git commit with all current changes in the given path.
Creates a mix project fixture under the given workspace path.
Creates a workspace fixture at the given path.
Runs the given test function unloading at the end any module or package initialized
from within the given path
.
Initializes a git repository in the given path.
Simulates a modification to a project in the workspace by creating a dummy file.
Creates a virtual fixture for a mix project.
Runs the given test_fn
in a temporary workspace under the given path
.
Generates a virtual workspace fixture.
Types
Functions
Asserts that the captured cli output matches the expected value with respect to the given options.
This helper assertion function provides some conveniences for working with cli output assertions.
Options
:trim_trailing_newlines
- if set trailing newlines are ignored.:trim_whitespace
- if set either leading or trailing whitespace is ignored from each line of the output.:trim_leading
- if set leading whitespace is ignored from each line of the output.:trim_trailing
- if set trailing whitespace is ignored from each line of the output.
If no option is set a strict equality check is performed.
Notice that all trimming operations (if needed) will happen both on the captured, and expected strings.
Creates a git commit with all current changes in the given path.
This is a helper function for testing that creates a commit with the message "changes" after staging all modifications.
Examples
commit_changes("path/to/workspace")
Creates a mix project fixture under the given workspace path.
The path
is expected to be the relative path with respect to the workspace_path
where
the project will be located.
You can pass either a project config which will be merged with some default settings
and persisted, or directly the contents of the mix file. Notice that in the latter case
app
is not used.
For example by calling:
create_mix_project("path/to/workspace", :foo, "packages/foo", [description: "The foo project"])
will write the following to path/to/workspace/packages/foo/mix.exs
:
defmodule Foo.MixProject do
use Mix.Project
def project do
[
app: :foo,
elixir: "~> 1.14",
start_permanent: false,
elixirc_paths: [],
description: "The foo project"
]
end
end
Options
:formatter
- Whether to add a default.formatter.exs
, defaults totrue
:lib_folder
- Whether to create an emptylib
sub folder, defaults totrue
Creates a workspace fixture at the given path.
It expects a workspace path, configuration, and either a predefined fixture or a list of projects to be created.
Raises an ArgumentError
if the workspace path is not empty
Options
:projects
- Additional project configuration to merge, defaults to[]
. This is useful if you want to update the project configuration of a default fixture. For example in order to add a description to thepackage_a
project you can do:create_workspace("path/to/workspace", [], :default, projects: [package_a: [description: "Package A"]] )
:workspace_module
- Optional name for the workspace module fixture. If not set defaults toTestWorkspace
Examples
# Using default fixture
create_workspace("tmp/test_workspace", [], :default)
# Using custom projects
create_workspace("tmp/test_workspace", [], [
{:app_a, "packages/app_a", [description: "App A"]},
{:app_b, "packages/app_b", [deps: [{:app_a, path: "../app_a"}]]}
])
Runs the given test function unloading at the end any module or package initialized
from within the given path
.
path
is considered to be the fixture path. Any module that will be loaded during the
test_fn
execution will be purged and deleted at the end.
It is advised to use this on any test that requires a fixture, in order to avoid warnings about redefining packages.
Initializes a git repository in the given path.
Creates an initial commit with all files in the path and sets the default branch to main
.
Examples
init_git_project("path/to/workspace")
Simulates a modification to a project in the workspace by creating a dummy file.
Creates an empty file at lib/file.ex
in the specified project path to simulate
project modifications. This is useful for testing workspace change detection.
Raises an ArgumentError
if the project path does not exist
Options
:file
- The relative path of the file with respect of the project dir to be added. Defaults tolib/file.ex
Examples
modify_project("/path/to/workspace", "packages/foo")
@spec project_fixture( app :: atom(), path :: Path.t(), config :: keyword(), opts :: keyword() ) :: Workspace.Project.t()
Creates a virtual fixture for a mix project.
It expects the app
name, a path
relative to the workspace which indicates
the project's location and a project config.
Tests using this function can be safely executed in async
mode.
Options
workspace_path
- The absolute workspace path to which this project belongs. If not set defaults to/usr/local/workspace
.
Examples
iex> Workspace.Test.project_fixture(:foo, "packages/foo", [description: "the foo package"])
%Workspace.Project{
app: :foo,
module: :"Foo.MixProject",
config: [description: "the foo package", app: :foo],
mix_path: "/usr/local/workspace/packages/foo/mix.exs",
path: "/usr/local/workspace/packages/foo",
workspace_path: "/usr/local/workspace",
skip: false,
status: :undefined,
root?: nil,
changes: nil,
tags: []
}
Notice that if path
is not a relative path an exception will be raised.
Virtual fixture
Notice that this creates an in-memory virtual fixture. This means that the underlying mix project does not exist and is not loaded.
If you want to test something on an actual project you should use the with_workspace/5
instead which generates the actual fixtures and loads them in memory.
Runs the given test_fn
in a temporary workspace under the given path
.
You can pass a predefined fixture or a list of projects to be created. Check create_workspace/4
for more details.
Options
:projects
- Additional project configuration to merge, defaults to[]
. This is useful if you want to update the project configuration of a default fixture. For example in order to add a description to thepackage_a
project you can do:with_workspace( "tmp/test_workspace", [], :default, fn -> # test code here end, projects: [package_a: [description: "Package A"]] )
:cd
- Whether to change directory to the workspace path, defaults tofalse
:git
- Whether to initialize the workspace as a git repository, defaults tofalse
Cleanup
The fixture directory is automatically removed after the test function completes.
Use create_workspace/4
directly if you need to preserve the workspace for multiple tests.
Examples
# Using default fixture
with_workspace("tmp/test_workspace", [], :default, fn ->
# Test code here
end)
# Using custom projects
with_workspace("tmp/test_workspace", [], [
{:app_a, "packages/app_a", [description: "App A"]},
{:app_b, "packages/app_b", [deps: [{:app_a, path: "../app_a"}]]}
], fn ->
# Test code here
end, git: true)
@spec workspace_fixture( projects_or_fixture :: atom() | [Workspace.Project.t() | project_fixture()], opts :: keyword() ) :: Workspace.State.t()
Generates a virtual workspace fixture.
It expects one of the following:
- A list of
Workspace.Project
structs. - A list of tuples of the form,
{app, path, config}
which will be used for generating project fixtures (seeproject_fixture/4
for more details) - An atom representing a default fixture.
Virtual fixture
Notice that this creates an in-memory virtual fixture. This means that the underlying mix projects do not exist and are not loaded.
If you want to test something on an actual project you should use the with_workspace/5
instead which generates the actual fixtures and loads them in memory.
Options
workspace_path
- The absolute workspace path to which this project belongs. If not set defaults to/usr/local/workspace
.