nx-plugins

This monorepo is managed with pnpm workspaces and Nx (version 22.3.3). The workspace layout is configured via nx.json with appsDir set to e2e and libsDir set to packages.

Directory Layout

• packages/: Contains all publishable projects and libraries.
• e2e/: Contains end-to-end testing projects.
• tools/: Contains workspace-wide tooling and scripts.
• types/: Contains ambient type declarations.

Available Packages

The @nxlv/python plugin provides a unified abstraction for managing Python projects within an Nx workspace, supporting both Poetry and uv package managers.

Instead of calling package managers directly, the plugin uses a Provider abstraction (src/provider/). This allows executors and generators to perform operations like install, build, lock, or sync without needing to know which specific package manager is being used.

Package Manager Resolution Logic: When you run a command, the plugin determines the provider using getProvider in this order:

1. Explicit Configuration: If the packageManager option is set to 'poetry' or 'uv', that manager is used.
2. Auto-detection: The plugin inspects the project's pyproject.toml and looks for lockfiles (uv.lock vs poetry.lock).
3. Fallback: If no lockfiles are found and no configuration is provided, it defaults to Poetry.

Note: If both uv.lock and poetry.lock are present, the plugin will throw an error due to ambiguity.

When testing executors or providers, the goal is to mock the filesystem and child processes to avoid hitting the real OS.

Key Strategies

1. Mock Executable Checks: Use vi.spyOn on utility modules (e.g., poetryUtils.checkPoetryExecutable) to return undefined so tests don't require real binaries.
2. Mock Shell Commands: Use vi.mocked(spawn.sync).mockReturnValue(...) to simulate command execution.
3. Stub Process Changes: Stub process.chdir since executors typically change directory into the workspace root.
4. Verify via Memfs: Assert that the correct files (like pyproject.toml) were written by reading them from the memfs volume.
5. Cleanup: Always call vol.reset() and vi.resetAllMocks() in an afterEach block to ensure test isolation.

describe('Add Executor', () => {
  afterEach(() => {
    vol.reset(); // wipe the in-memory FS
    vi.resetAllMocks();
  });

  describe('poetry', () => {
    beforeEach(() => {
      vi.spyOn(poetryUtils, 'checkPoetryExecutable').mockResolvedValue(undefined);
      vi.spyOn(poetryUtils, 'getPoetryVersion').mockResolvedValue('1.8.2');
      vi.spyOn(PoetryProvider.prototype, 'activateVenv').mockResolvedValue(undefined);
      vi.mocked(spawn.sync).mockReturnValue({ status: 0, output: [''], pid: 0, signal: null, stderr: null, stdout: null });
      vi.spyOn(process, 'chdir').mockReturnValue(undefined);
    });
    // ... assertions
  });
});

When testing Nx generators, use an in-memory Nx Tree instead of the real filesystem. This ensures tests are fast and do not leave side effects on your workspace.

Implementation Steps

1. Initialize Tree: Use createTreeWithEmptyWorkspace({ layout: 'apps-libs' }) from @nx/devkit/testing to create a fresh in-memory workspace.
2. Run Generator: Pass the appTree to your generator function.
3. Verify with Snapshots: Use expect(...).toMatchSnapshot() to verify the state of the project configuration and generated files.
4. Read Results: Use @nx/devkit helpers like readProjectConfiguration, readNxJson, or tree.read(path, 'utf-8') to inspect the tree.

Updating Snapshots

If you intentionally change the generator output, update the snapshots using:

pnpm nx test <package-name> -- -u

import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
import { Tree, readProjectConfiguration, readNxJson } from '@nx/devkit';
import generator from './generator';

let appTree: Tree;

beforeEach(() => {
  vi.resetAllMocks();
  appTree = createTreeWithEmptyWorkspace({ layout: 'apps-libs' });
});

it('scaffolds the project', async () => {
  await generator(appTree, options);
  expect(readProjectConfiguration(appTree, 'test')).toMatchSnapshot();
  expect(appTree.read('test/pyproject.toml', 'utf-8')).toMatchSnapshot();
});