The workspace configuration.

The workspace configuration is specified usually in a .workspace.exs file in the root of your workspace. This is the place to:

• Configure your workspace checks (Workspace.Check)
• Specify paths or projects to be ignored during the workspace graph generation
• Define overall workspace coverage thresholds
• Define any other configuration option may be needed by a third party plugin.

It is expected to be a keyword list with an arbitrary set of configuration options.

Options

The following configuration options are supported by default:

• :ignore_projects (list of atom/0) - A list of project modules to be ignored. If set these projects will not be considered workspace projects when initializing a Workspace with the current config. The default value is [].

• :ignore_paths (list of String.t/0) - List of paths relative to the workspace root to be ignored from parsing for projects detection. The default value is [].

• :checks (list of keyword/0) - List of checks configured for the workspace. For more details check Workspace.Check The default value is [].

• :groups_for_checks (non-empty keyword/0) - Allows you to configure the look and feel of the checks group headings. It expects a keyword list, where the key is the group identifier and the value is the configuration for this specific group heading, for example:

  groups_for_checks: [
    package: [
      title: "-> Package checks",
      style: [:red]
    ],
    docs: [
      title: " 📚 Documentation checks",
      style: [:yellow_background, :white]
    ]
  ]

  Each group style definition is expected to be a keyword list with the following options:

  • :title (String.t/0) - The title of the check group, if not set defaults to the group name

  • :style (list of atom/0) - The ANSI style for the group heading. You can use it to modify the look of this specific header. For example in order to make the background blue and the text red you can set the style to:

    style: [:blue_background, :red]

    For more details check the IO.ANSI docs.

• :test_coverage (keyword/0) - Test coverage configuration for the workspace. Notice that this is independent of the test_coverage configuration per project. It is applied in the aggregate coverage and except thresholds you can also configure coverage exporters. The default value is [].

  • :threshold (non_neg_integer/0) - The overall coverage threshold for the workspace. If the overall test coverage is below this value then the workspace.test.coverage command is considered failed. Notice that the overall test coverage percentage is calculated only on the enabled projects. The default value is 90.

  • :warning_threshold (non_neg_integer/0) - If set it specifies an overall warning threshold under which a warning will be raised. If not set it is implied to be the mid value between threshold and 100.

  • :exporters (keyword/0) - Definition of exporters to be used. Each defined exporter must be an anonymous function taking as input the workspace and the coverage_stats. For more details check the Mix.Tasks.Workspace.Test.Coverage task.

  • :allow_failure (list of atom/0) - A list of projects for which the test coverage is allowed to fail without affecting the overall status. The default value is [].

A simple example of a .workspace.exs follows:

[
  ignore_paths: ["deps", "artifacts", "cover"],
  checks: [
    # Add your checks here
    [
      module: Workspace.Checks.ValidateProject,
      description: "all projects must have a description set",
      opts: [
        validate: fn project ->
          case project.config[:description] do
            nil -> {:error, "no :description set"}
            description when is_binary(description) -> {:ok, ""}
            other -> {:error, "description must be binary, got: #{inspect(other)}"}
          end
        end
      ]
    ]
  ],
  test_coverage: [
    allow_failure: [:foo],
    threshold: 98,
    warning_threshold: 99,
    exporters: [
      lcov: fn workspace, coverage_stats ->
        Workspace.Coverage.LCOV.export(workspace, coverage_stats,
          output_path: "artifacts/coverage"
        )
      end
    ]
  ],
  my_awesome_plugin_options: [
    x: 1,
    y: 2
  ]
]