For the complete documentation index, see llms.txt. This page is also available as Markdown.

Create The Scope

Access the Kotlin files using Konsist API

Scope represents a set of Kotlin files to be further queried, filtered (Declaration Filtering), and verified (Declaration Assertion).

Scopes are an alternative to a baseline file. Subsets of the codebase can be refactored to be aligned with Konsist tests e.g. code in a single module.

Every scope contains a set of KoFile instances. Every KoFile instance contains the declarations (see Declaration) representing code entities present in the file e.g.:

Konsist is built on top of Kotlin Compiler Psi. It wraps the Kotlin compiler parser and provides a simple API to access Kotlin codebase declarations. Konsist Declaration tree mimics the Kotlin code structure.

The scope can be created for an entire project, module, package, and Kotlin file.

The scope is dynamically built based on the Kotlin files present in the project, enabling it to adapt seamlessly as the project evolves. For instance, when the scope is set to encapsulate a specific module, any additional file introduced to that module will be automatically incorporated into the scope. This ensures that the scope consistently offers thorough and current coverage.

Scope Creation

Various methods can be used to obtain instances of the scope. This allows the definition of more granular Konsist tests e.g. tests covering only certain modules, source sets, packages, or folders.

Project Scope

The widest scope is the scope containing all Kotlin files present inside the project:

Project scopes (scopeFromProject, scopeFromModule, scopeFromPackage, scopeFromSourceSet, scopeFromProduction and scopeFromTest) contain only Kotlin files located in the module src directory. Kotlin files located outside of it are ignored, e.g. app/Script.kt, app/testData/Fixture.kt and app/build/Generated.kt. Use Directory Scope or File Scope to verify these files.

To print a list of files within koScope use the koScope.print() method:

To review the scope content in more detail see Debug Konsist Test.

Production Codebase

The scopeFromProduction method allows the creation of a scope containing only production code (equivalent to Konsist.scopeFromProject() - Konsist.scopeFromTest()):

Contains:

A test source set is a source set whose name contains test (case-insensitive), e.g. test, androidTest, testFixtures or konsistTest. Every other source set (e.g. main) is a production source set.

Passing a test source set to scopeFromProduction(sourceSetName = ...) or a production source set to scopeFromTest(sourceSetName = ...) throws IllegalArgumentException.

Test Codebase

The scopeFromTest method allows the creation of a scope containing only test code:

Contains:

Module Scope

The scopeFromModule method allows the creation of more granular scopes based on the module name e.g. creating a scope containing all Kotlin files present in the app module:

Contains:

The module name can be passed in any of these formats:

  • Gradle project path, e.g. :feature:auth or feature:auth (preferred)

  • Directory path with / or \ separators, e.g. feature/auth or feature\auth (both accepted on all OSes)

Leading and trailing separators are ignored, e.g. /feature/auth/ is treated as feature/auth.

The top-level (root) module can be referenced as : or root. Module names are case-sensitive on all OSes (:App does not match the app directory).

Konsist resolves the module name to a directory relative to the project root (:feature:auth -> feature/auth). Gradle modules with a custom projectDir (set in settings.gradle.kts) must be referenced by their directory path.

This approach may be helpful when refactoring an existing project module by module.

Nested Module Scope

A nested module is a module that exists within another module.

Consider this feature module existing inside app module:

To narrow the scope to feature module use:

Modules can be nested at any depth (e.g. :app:feature:payment). The module name is always the full path from the project root, so scopeFromModule(":feature") does not match the app/feature module.

The parent module scope contains only the parent module files - files of nested modules are not included:

To include the parent module and its nested modules pass all of them:

or use the .. wildcard, which matches any number of module directories (including none):

The wildcard works with every method accepting a module name, e.g. the moduleName parameter of scopeFromProject, scopeFromPackage, scopeFromProduction and scopeFromTest, as well as residesInModule, withModule and withoutModule:

Module names without .. must match exactly, so :app does not include :app:feature. More than two consecutive dots (e.g. :app...) are not allowed and throw IllegalArgumentException.

Use .. (or :..) to match all modules. root.. matches only the root module and modules located in a directory named root.

The moduleName property of a nested module declaration returns the directory path with / separators on all OSes (e.g. app/feature).

A module can also be located in a directory named src, e.g. the src/tools/src/main/kotlin/Tools.kt file resides in the src/tools module:

A project located inside a source set directory is not a nested module. Its files belong to the module containing the source set. A source set directory is a directory containing a kotlin, java or resources directory (e.g. app/src/test).

Both Fixture.kt files reside in the app module and the test source set:

Source Set Scope

The scopeFromSourceSet method allows the creation of more granular scopes based on the source set name e.g. create a scope containing all Kotlin files present in the test source set:

Contains:

The source set is the directory located directly in the module src directory, e.g. test for both app/src/test/kotlin/AppTest.kt and app/src/test/resources/Fixture.kt. Leading and trailing separators are ignored (test/ is treated as test).

Module and Source Set Scope

To retrieve scope by using both module and source set use the scopeFromProject method with moduleName and sourceSetName arguments:

The moduleName argument (also available in scopeFromProduction, scopeFromTest and scopeFromPackage) accepts the same formats as scopeFromModule and returns an empty scope when the module does not exist.

Contains:

Package Scope

The scopeFromPackage method allows the creation of a scope containing code present in a given package e.g. com.usecase package:

Contains:

Files are selected by the package declared in the file (package com.usecase), not by the directory structure. The scope can be narrowed down further with the moduleName and sourceSetName arguments:

The double dots (..) syntax means zero or more packages. Check the Package Wildcard page.

Directory Scope

The scopeFromDirectory method allows the creation of a scope containing code present in a given project folder e.g. domain directory. Unlike project scopes, it also contains Kotlin files located outside the module src directory:

Contains:

The path is relative to the project root. Both / and \ separators are accepted on all OSes.

Build output directories (build, target) located outside the src directory, hidden directories (e.g. .gradle, .idea) and node_modules directories located inside the given directory are skipped, the same way as for project scopes. A skipped directory can still be passed explicitly, e.g. to verify generated code:

Letter case follows the file system: on case-sensitive file systems (Linux) app/src does not match the App/src directory, on case-insensitive ones (macOS, Windows) it does.

To create a scope from a directory located outside the project use scopeFromExternalDirectory with an absolute path. Some file properties, such as projectPath and moduleName, do not work for these files:

File Scope

It is also possible to create scope from one or more file paths:

The path is relative to the project root. Both / and \ separators are accepted on all OSes. Letter case should match the file system. On case-sensitive file systems (e.g. Linux) a path with different letter case (e.g. App/src instead of app/src) throws IllegalArgumentException.

It is also possible to create the scope from a list of files. This can help with certain development workflows e.g. running Konsist tests only on files modified in a given PR:

Scope Slice

For even more granular control you can use the KoScope.slice method to retrieve a scope containing a subset of files from the given scope:

Project files are parsed once and cached, so slicing Konsist.scopeFromProject() does not parse files again.

Scope Reuse

Reuse Scope In Test Class

To reuse the scope across the test class, define the scope in the companion object and access it from multiple tests:

Reuse Scope In Test Source Set

To reuse the scope across multiple test classes, define the scope in a file and access it from multiple test classes:

Here is the file structure representing the above snippet:

Scope Composition

Konsist scope supports Kotlin Operator overloading, so scopes can be further combined together to create the desired scope, tailored to project needs. In this example scopes from myFeature1 module and myFeature2 module are combined together:

A file present in both scopes is included in the combined scope only once.

The += and -= operators modify the scope in place:

Scope Subtraction

Scope subtraction is also supported, so it is possible for example to exclude a part of a given module. Here scope is created from myFeature module and then the ..data.. package is excluded:

To print all files within the scope use the print() method:

Access Specific Declarations

To access specific declaration types such as interfaces, classes, constructors, functions, etc. utilize the Declaration Filtering.

Last updated