Project configuration

Configuration locations#

Test Chronicle keeps configuration in four places, each with a different responsibility.

The repository file links a checkout to a Test Chronicle project. It does not define frameworks, test directories, project areas, or classification rules.

{
  "projectId": "your-project-id"
}

Prefer automatic behaviour#

Test Chronicle detects supported frameworks, conventional test locations, the repository default branch, testing levels, common monorepo areas, and product-like areas in centralized test suites. Most projects should keep these settings automatic.

Add an override when the dashboard preview or a local sync shows that repository conventions are not enough. Overrides are project-level and do not need to be committed to the repository.

Dashboard settings#

Open a project and select Settings. The configuration workflow is organised into four focused sections.

Each section has independent unsaved changes and its own Save action. Reset to automatic removes only the overrides owned by that section.

General settings manage project identity. Activity shows sync freshness, diagnostics, and recent runs. Danger zone contains project deletion. They are administrative settings rather than sync configuration.

Testing type classification#

The former classification section on this page has moved to the dedicated Testing classification reference.

The existing link remains here for compatibility. Classification changes how already discovered files are grouped; it does not change which files the sync agent discovers.

Local credentials#

The CLI stores its project-scoped token in your user configuration directory, outside the repository. Do not add that token to source control.

Use these commands to inspect or remove local state:

npx testchronicle@latest status
npx testchronicle@latest logout

GitHub Actions#

The GitHub Action accepts API_KEY and PROJECT_ID. Store both as GitHub Actions secrets. Values supplied by CI take precedence over local credentials and the repository project file.

Dashboard configuration is fetched by the sync agent at the beginning of a run. Discovery changes therefore apply to the next local or CI sync. Branch tracking comes from the repository default branch detected by the sync agent.

SyncConfig appendix#

The dashboard is the supported way to edit project configuration. The stored JSON shape is included to make support discussions, exports, and API responses easier to understand.

interface SyncConfig {
  frameworkOverrides?: Array<{
    framework: string
    dirs: string[]
  }>
  testDirExcludes?: string[]
  primaryFramework?: string
  testLevelMappings?: {
    frameworkDefaults?: Record<string, 'unit' | 'integration' | 'component' | 'e2e' | 'unknown'>
    pathOverrides?: Array<{
      level: 'unit' | 'integration' | 'component' | 'e2e' | 'unknown'
      patterns: string[]
    }>
  }
  projectAreaMappings?: Array<{
    id: string
    label: string
    // Multiple repository-relative glob patterns can map to one area.
    patterns: string[]
  }>
}

Fields that are absent use automatic behaviour. Saving one settings section preserves fields owned by the other sections.