@opentrons/shared-data 0.1.2-alpha.0 → 0.1.2-alpha.1

package/js/helpers/__tests__/parseProtocolData.test.ts

@@ -0,0 +1,165 @@
+// json protocol file validator tests
+import fixtureV1JsonProtocol from '../../../protocol/fixtures/1/simple.json'
+import fixtureV3JsonProtocol from '../../../protocol/fixtures/3/simple.json'
+import fixtureV4JsonProtocol from '../../../protocol/fixtures/4/simpleV4.json'
+import fixtureV5JsonProtocol from '../../../protocol/fixtures/5/simpleV5.json'
+import {
+  fileExtensionIsPython,
+  fileExtensionIsJson,
+  fileExtensionIsZip,
+  validateJsonProtocolFileContents,
+  parseProtocolData,
+} from '../parseProtocolData'
+
+describe('validateJsonProtocolFileContents', () => {
+  let handleError: jest.MockedFunction<any>
+  // beforeAll
+
+  beforeEach(() => {
+    handleError = jest.fn()
+  })
+
+  afterEach(() => {
+    jest.resetAllMocks()
+  })
+
+  it(`should validate schemaV3 JSON protocol`, () => {
+    const data = validateJsonProtocolFileContents(
+      JSON.stringify(fixtureV3JsonProtocol)
+    )
+    expect(data).toStrictEqual(fixtureV3JsonProtocol)
+  })
+
+  it(`should validate schemaV4 JSON protocol`, () => {
+    const data = validateJsonProtocolFileContents(
+      JSON.stringify(fixtureV4JsonProtocol)
+    )
+    expect(data).toStrictEqual(fixtureV4JsonProtocol)
+  })
+
+  it(`should validate schemaV5 JSON protocol`, () => {
+    const data = validateJsonProtocolFileContents(
+      JSON.stringify(fixtureV5JsonProtocol)
+    )
+    expect(data).toStrictEqual(fixtureV5JsonProtocol)
+  })
+
+  it('should call handleError with INVALID_FILE_TYPE if empty json', () => {
+    validateJsonProtocolFileContents('[]', handleError)
+    expect(handleError).toBeCalledWith('INVALID_JSON_FILE', {
+      rawError: expect.any(Error),
+    })
+  })
+
+  it('should call handleError with INVALID_JSON_FILE if json does not validate against schema', () => {
+    validateJsonProtocolFileContents(
+      JSON.stringify(fixtureV1JsonProtocol),
+      handleError
+    )
+    expect(handleError).toBeCalledWith('INVALID_JSON_FILE', {
+      schemaErrors: expect.any(Array),
+    })
+  })
+
+  it('should call handleError with INVALID_JSON_FILE if json is not parseable', () => {
+    const parseSpy = jest.spyOn(JSON, 'parse')
+    parseSpy.mockImplementation(() => {
+      throw new Error('not parseable as JSON')
+    })
+    validateJsonProtocolFileContents('[]', handleError)
+    expect(handleError).toBeCalledWith('INVALID_JSON_FILE', {
+      rawError: expect.any(Error),
+    })
+    parseSpy.mockRestore()
+  })
+})
+
+describe('file extension validators', () => {
+  describe('fileExtensionIsPython', () => {
+    it(`should return true if file name ends in .py`, () => {
+      expect(fileExtensionIsPython('foo.py')).toBe(true)
+    })
+    it(`should return false if file name ends in anything other than .py`, () => {
+      expect(fileExtensionIsPython('foo.json')).toBe(false)
+      expect(fileExtensionIsPython('foo.zip')).toBe(false)
+      expect(fileExtensionIsPython('foo.pie')).toBe(false)
+    })
+  })
+  describe('fileExtensionIsJson', () => {
+    it(`should return true if file name ends in .json`, () => {
+      expect(fileExtensionIsJson('foo.json')).toBe(true)
+    })
+    it(`should return false if file name ends in anything other than .json`, () => {
+      expect(fileExtensionIsJson('foo.py')).toBe(false)
+      expect(fileExtensionIsJson('foo.zip')).toBe(false)
+      expect(fileExtensionIsJson('foo.pie')).toBe(false)
+    })
+  })
+  describe('fileExtensionIsZip', () => {
+    it(`should return true if file name ends in .zip`, () => {
+      expect(fileExtensionIsZip('foo.zip')).toBe(true)
+    })
+    it(`should return false if file name ends in anything other than .zip`, () => {
+      expect(fileExtensionIsZip('foo.py')).toBe(false)
+      expect(fileExtensionIsZip('foo.json')).toBe(false)
+      expect(fileExtensionIsZip('foo.pie')).toBe(false)
+    })
+  })
+  describe('fileIsBinary', () => {
+    it(`should return true if file name ends in .zip`, () => {
+      expect(fileExtensionIsZip('foo.zip')).toBe(true)
+    })
+    it(`should return false if file name ends in anything other than .zip`, () => {
+      expect(fileExtensionIsZip('foo.py')).toBe(false)
+      expect(fileExtensionIsZip('foo.json')).toBe(false)
+      expect(fileExtensionIsZip('foo.pie')).toBe(false)
+    })
+  })
+})
+
+describe('parseProtocolData', () => {
+  let handleError: jest.MockedFunction<any>
+  beforeEach(() => {
+    handleError = jest.fn()
+  })
+
+  afterEach(() => {
+    jest.resetAllMocks()
+  })
+
+  it(`should return null if not JSON and metadata not given`, () => {
+    const contents = 'from math import sqrt'
+    const pythonFile = new File([contents], 'foo.py')
+    expect(parseProtocolData(pythonFile, contents)).toBe(null)
+  })
+  it(`should return metadata if not JSON and metadata is given`, () => {
+    const contents = 'from math import sqrt'
+    const pythonFile = new File([contents], 'foo.py')
+    const metadata = {
+      'protocol-name': 'Foo Extraction',
+      author: 'Dr. Bar Baz',
+    } as any
+    expect(
+      parseProtocolData(pythonFile, contents, handleError, metadata)
+    ).toStrictEqual({ metadata })
+  })
+  it(`should return JSON protocol file if valid json protocol given`, () => {
+    const contents = JSON.stringify(fixtureV5JsonProtocol)
+    const jsonFile = new File([contents], 'valid.json')
+    expect(parseProtocolData(jsonFile, contents, handleError)).toStrictEqual(
+      fixtureV5JsonProtocol
+    )
+  })
+  it(`should call handleError if given JSON protocol not valid`, () => {
+    const contents = JSON.stringify(fixtureV1JsonProtocol)
+    const jsonFile = new File([contents], 'invalid.json')
+    expect(parseProtocolData(jsonFile, contents, handleError)).toBe(null)
+    expect(handleError).toHaveBeenCalled()
+  })
+  it(`should call handleError if given invalid file extension`, () => {
+    const contents = JSON.stringify(fixtureV1JsonProtocol)
+    const jsonFile = new File([contents], 'invalid.foobar')
+    expect(parseProtocolData(jsonFile, contents, handleError)).toBe(null)
+    expect(handleError).toHaveBeenCalledWith('INVALID_FILE_TYPE')
+  })
+})

package/js/helpers/__tests__/volume.test.ts

@@ -0,0 +1,108 @@
+// volume helpers tests
+import * as helpers from '..'
+
+interface BaseSpec<T extends (...args: any) => any> {
+  name: string
+  func: T
+  input: Parameters<T>
+  expected: ReturnType<T>
+}
+
+type GetDisplayVolumeSpec = BaseSpec<typeof helpers.getDisplayVolume>
+
+type GetAsciiVolumeUnitsSpec = BaseSpec<typeof helpers.getAsciiVolumeUnits>
+
+type EnsureVolumeUnitsSpec = BaseSpec<typeof helpers.ensureVolumeUnits>
+
+type TestSpec =
+  | GetDisplayVolumeSpec
+  | GetAsciiVolumeUnitsSpec
+  | EnsureVolumeUnitsSpec
+
+describe('volume helpers', () => {
+  const SPECS: TestSpec[] = [
+    {
+      name: 'getDisplayVolume outputs µL string by default',
+      func: helpers.getDisplayVolume,
+      input: [380],
+      expected: '380',
+    },
+    {
+      name: 'getDisplayVolume converts to mL',
+      func: helpers.getDisplayVolume,
+      input: [4200, 'mL'],
+      expected: '4.2',
+    },
+    {
+      name: 'getDisplayVolume converts to L',
+      func: helpers.getDisplayVolume,
+      input: [800000, 'L'],
+      expected: '0.8',
+    },
+    {
+      name: 'getDisplayVolume can round to fixed digits',
+      func: helpers.getDisplayVolume,
+      input: [123456789, 'L', 3],
+      expected: '123.457',
+    },
+    {
+      name: 'getAsciiVolumeUnits converts µL to uL',
+      func: helpers.getAsciiVolumeUnits,
+      input: ['µL'],
+      expected: 'uL',
+    },
+    {
+      name: 'getAsciiVolumeUnits leaves mL alone',
+      func: helpers.getAsciiVolumeUnits,
+      input: ['mL'],
+      expected: 'mL',
+    },
+    {
+      name: 'getAsciiVolumeUnits leaves L alone',
+      func: helpers.getAsciiVolumeUnits,
+      input: ['L'],
+      expected: 'L',
+    },
+    {
+      name: 'ensureVolumeUnits converts undefined to µL',
+      func: helpers.ensureVolumeUnits,
+      input: [undefined],
+      expected: 'µL',
+    },
+    {
+      name: 'ensureVolumeUnits converts uL to µL',
+      func: helpers.ensureVolumeUnits,
+      input: ['uL'],
+      expected: 'µL',
+    },
+    {
+      name: 'ensureVolumeUnits leaves mL alone',
+      func: helpers.ensureVolumeUnits,
+      input: ['mL'],
+      expected: 'mL',
+    },
+    {
+      name: 'ensureVolumeUnits leaves L alone',
+      func: helpers.ensureVolumeUnits,
+      input: ['L'],
+      expected: 'L',
+    },
+    {
+      name: 'ensureVolumeUnits converts ml to mL',
+      func: helpers.ensureVolumeUnits,
+      input: ['ml'],
+      expected: 'mL',
+    },
+    {
+      name: 'ensureVolumeUnits leaves l to L',
+      func: helpers.ensureVolumeUnits,
+      input: ['l'],
+      expected: 'L',
+    },
+  ]
+
+  SPECS.forEach(s => {
+    // @ts-expect-error(mc, 2021-04-27): rewrite as regular tests
+    it(`should ${s.name}`, () => expect(s.func(...s.input)).toEqual(s.expected))
+  })
+})

package/js/helpers/__tests__/wellSets.test.ts

@@ -0,0 +1,352 @@
+import pipetteNameSpecsFixtures from '../../../pipette/fixtures/name/pipetteNameSpecFixtures.json'
+import fixture_12_trough from '../../../labware/fixtures/2/fixture_12_trough.json'
+import fixture_96_plate from '../../../labware/fixtures/2/fixture_96_plate.json'
+import fixture_384_plate from '../../../labware/fixtures/2/fixture_384_plate.json'
+import fixture_overlappy_wellplate from '../../../labware/fixtures/2/fixture_overlappy_wellplate.json'
+import { makeWellSetHelpers } from '../wellSets'
+import { findWellAt } from '../getWellNamePerMultiTip'
+import { get96Channel384WellPlateWells, orderWells } from '..'
+
+import type { LabwareDefinition2, PipetteNameSpecs } from '../../types'
+import type { WellSetHelpers } from '../wellSets'
+
+const fixtureP10Single = pipetteNameSpecsFixtures.p10_single as PipetteNameSpecs
+const fixtureP10Multi = pipetteNameSpecsFixtures.p10_multi as PipetteNameSpecs
+const fixtureP100096 = (pipetteNameSpecsFixtures.p1000_96 as any) as PipetteNameSpecs
+const fixture12Trough = fixture_12_trough as LabwareDefinition2
+const fixture96Plate = fixture_96_plate as LabwareDefinition2
+const fixture384Plate = fixture_384_plate as LabwareDefinition2
+const fixtureOverlappyWellplate = fixture_overlappy_wellplate as LabwareDefinition2
+const EIGHT_CHANNEL = 8
+const NINETY_SIX_CHANNEL = 96
+const wellsForReservoir = [
+  'A1',
+  'A2',
+  'A3',
+  'A4',
+  'A5',
+  'A6',
+  'A7',
+  'A8',
+  'A9',
+  'A10',
+  'A11',
+  'A12',
+]
+
+const wellsFor96WellPlate = [
+  'A1',
+  'B1',
+  'C1',
+  'D1',
+  'E1',
+  'F1',
+  'G1',
+  'H1',
+  'A2',
+  'B2',
+  'C2',
+  'D2',
+  'E2',
+  'F2',
+  'G2',
+  'H2',
+  'A3',
+  'B3',
+  'C3',
+  'D3',
+  'E3',
+  'F3',
+  'G3',
+  'H3',
+  'A4',
+  'B4',
+  'C4',
+  'D4',
+  'E4',
+  'F4',
+  'G4',
+  'H4',
+  'A5',
+  'B5',
+  'C5',
+  'D5',
+  'E5',
+  'F5',
+  'G5',
+  'H5',
+  'A6',
+  'B6',
+  'C6',
+  'D6',
+  'E6',
+  'F6',
+  'G6',
+  'H6',
+  'A7',
+  'B7',
+  'C7',
+  'D7',
+  'E7',
+  'F7',
+  'G7',
+  'H7',
+  'A8',
+  'B8',
+  'C8',
+  'D8',
+  'E8',
+  'F8',
+  'G8',
+  'H8',
+  'A9',
+  'B9',
+  'C9',
+  'D9',
+  'E9',
+  'F9',
+  'G9',
+  'H9',
+  'A10',
+  'B10',
+  'C10',
+  'D10',
+  'E10',
+  'F10',
+  'G10',
+  'H10',
+  'A11',
+  'B11',
+  'C11',
+  'D11',
+  'E11',
+  'F11',
+  'G11',
+  'H11',
+  'A12',
+  'B12',
+  'C12',
+  'D12',
+  'E12',
+  'F12',
+  'G12',
+  'H12',
+]
+
+describe('findWellAt', () => {
+  it('should determine if given (x, y) is within a rectangular well', () => {
+    const def: any = {
+      wells: {
+        A1: {
+          shape: 'rectangular',
+          x: 200,
+          y: 200,
+          xDimension: 10,
+          yDimension: 10,
+        },
+      },
+    }
+    const middle = findWellAt(def, 200, 200)
+    expect(middle).toBe('A1')
+
+    const insideCornerNE = findWellAt(def, 200 - 4, 200 + 4)
+    expect(insideCornerNE).toEqual('A1')
+
+    // exactly at an edge doesn't count
+    const exactlyOnCornerNE = findWellAt(def, 200 - 5, 200 + 5)
+    expect(exactlyOnCornerNE).toBeUndefined()
+
+    const exactlyOnWEdge = findWellAt(def, 200, 200 - 5)
+    expect(exactlyOnWEdge).toBeUndefined()
+
+    const justOutsideToEast = findWellAt(def, 200 + 5.1, 200)
+    expect(justOutsideToEast).toBeUndefined()
+  })
+
+  it('should determine if given (x, y) is within a circular well', () => {
+    const def: any = {
+      wells: {
+        A1: {
+          shape: 'circular',
+          x: 200,
+          y: 200,
+          diameter: 10,
+        },
+      },
+    }
+    const middle = findWellAt(def, 200, 200)
+    expect(middle).toBe('A1')
+
+    const inside = findWellAt(def, 200 - 1, 200 + 1)
+    expect(inside).toEqual('A1')
+
+    // exactly at an edge doesn't count
+    const exactlyOnWEdge = findWellAt(def, 200, 200 - 5)
+    expect(exactlyOnWEdge).toBeUndefined()
+
+    const justOutsideToEast = findWellAt(def, 200 + 5.1, 200)
+    expect(justOutsideToEast).toBeUndefined()
+  })
+})
+describe('canPipetteUseLabware', () => {
+  let canPipetteUseLabware: WellSetHelpers['canPipetteUseLabware']
+
+  beforeEach(() => {
+    const helpers = makeWellSetHelpers()
+    canPipetteUseLabware = helpers.canPipetteUseLabware
+  })
+
+  it('returns false when wells are too close together for multi channel pipettes', () => {
+    const labwareDef = fixtureOverlappyWellplate
+    const pipette = fixtureP10Multi
+    const pipette96 = fixtureP100096
+
+    expect(canPipetteUseLabware(pipette, labwareDef)).toBe(false)
+    expect(canPipetteUseLabware(pipette96, labwareDef)).toBe(false)
+  })
+
+  it('returns true when pipette is single channel', () => {
+    const labwareDef = fixtureOverlappyWellplate
+    const pipette = fixtureP10Single
+
+    expect(canPipetteUseLabware(pipette, labwareDef)).toBe(true)
+  })
+})
+
+describe('getWellSetForMultichannel (integration test)', () => {
+  let getWellSetForMultichannel: WellSetHelpers['getWellSetForMultichannel']
+
+  beforeEach(() => {
+    const helpers = makeWellSetHelpers()
+    getWellSetForMultichannel = helpers.getWellSetForMultichannel
+  })
+
+  it('96-flat', () => {
+    const labwareDef = fixture96Plate
+
+    expect(getWellSetForMultichannel(labwareDef, 'A1', EIGHT_CHANNEL)).toEqual([
+      'A1',
+      'B1',
+      'C1',
+      'D1',
+      'E1',
+      'F1',
+      'G1',
+      'H1',
+    ])
+
+    expect(getWellSetForMultichannel(labwareDef, 'B1', EIGHT_CHANNEL)).toEqual([
+      'A1',
+      'B1',
+      'C1',
+      'D1',
+      'E1',
+      'F1',
+      'G1',
+      'H1',
+    ])
+
+    expect(getWellSetForMultichannel(labwareDef, 'H1', EIGHT_CHANNEL)).toEqual([
+      'A1',
+      'B1',
+      'C1',
+      'D1',
+      'E1',
+      'F1',
+      'G1',
+      'H1',
+    ])
+
+    expect(getWellSetForMultichannel(labwareDef, 'A2', EIGHT_CHANNEL)).toEqual([
+      'A2',
+      'B2',
+      'C2',
+      'D2',
+      'E2',
+      'F2',
+      'G2',
+      'H2',
+    ])
+
+    //  96-channel
+    expect(
+      getWellSetForMultichannel(labwareDef, 'A1', NINETY_SIX_CHANNEL)
+    ).toEqual(wellsFor96WellPlate)
+  })
+
+  it('invalid well', () => {
+    const labwareDef = fixture96Plate
+
+    expect(
+      getWellSetForMultichannel(labwareDef, 'A13', EIGHT_CHANNEL)
+    ).toBeFalsy()
+  })
+
+  it('trough-12row', () => {
+    const labwareDef = fixture12Trough
+
+    expect(getWellSetForMultichannel(labwareDef, 'A1', EIGHT_CHANNEL)).toEqual([
+      'A1',
+      'A1',
+      'A1',
+      'A1',
+      'A1',
+      'A1',
+      'A1',
+      'A1',
+    ])
+
+    expect(getWellSetForMultichannel(labwareDef, 'A2', EIGHT_CHANNEL)).toEqual([
+      'A2',
+      'A2',
+      'A2',
+      'A2',
+      'A2',
+      'A2',
+      'A2',
+      'A2',
+    ])
+
+    //  96-channel
+    expect(
+      getWellSetForMultichannel(labwareDef, 'A1', NINETY_SIX_CHANNEL)
+    ).toEqual(wellsForReservoir)
+  })
+
+  it('384-plate', () => {
+    const labwareDef = fixture384Plate
+    const well96Channel = 'A1'
+    const all384Wells = orderWells(labwareDef.ordering, 't2b', 'l2r')
+    const ninetySixChannelWells = get96Channel384WellPlateWells(
+      all384Wells,
+      well96Channel
+    )
+
+    expect(getWellSetForMultichannel(labwareDef, 'C1', EIGHT_CHANNEL)).toEqual([
+      'A1',
+      'C1',
+      'E1',
+      'G1',
+      'I1',
+      'K1',
+      'M1',
+      'O1',
+    ])
+
+    expect(getWellSetForMultichannel(labwareDef, 'F2', EIGHT_CHANNEL)).toEqual([
+      'B2',
+      'D2',
+      'F2',
+      'H2',
+      'J2',
+      'L2',
+      'N2',
+      'P2',
+    ])
+
+    //  96-channel
+    expect(
+      getWellSetForMultichannel(labwareDef, well96Channel, NINETY_SIX_CHANNEL)
+    ).toEqual(ninetySixChannelWells)
+  })
+})

package/js/helpers/get96Channel384WellPlateWells.ts

@@ -0,0 +1,44 @@
+//  TODO(jr, 10/19/23): should extend getWellNamePerMultiTip to use similar math for 96-channel and 384 well plates
+//  instead of special casing using this util
+export function get96Channel384WellPlateWells(
+  all384Wells: string[],
+  well: string
+): string[] {
+  const totalWells = 96 * 2 //  multiplying 2 because we will remove either odd or even numbers
+
+  const filterWellsFor96Channel = (start: number, isOdd: boolean): string[] => {
+    const filteredWells: string[] = []
+    let count = start
+    for (let i = 0; i < totalWells; i++) {
+      if (count < all384Wells.length) {
+        const well = all384Wells[count]
+        const numberFromWell = well.match(/\d+/)
+        if (numberFromWell) {
+          const number = parseInt(numberFromWell[0])
+          if ((number % 2 === 1 && isOdd) || (number % 2 === 0 && !isOdd)) {
+            filteredWells.push(well)
+          }
+        }
+        count += 2
+      } else {
+        break
+      }
+    }
+    return filteredWells
+  }
+
+  const allSetsOfWells = [
+    filterWellsFor96Channel(0, true),
+    filterWellsFor96Channel(1, true),
+    filterWellsFor96Channel(0, false),
+    filterWellsFor96Channel(1, false),
+  ]
+
+  for (const wells of allSetsOfWells) {
+    if (wells.includes(well)) {
+      return wells
+    }
+  }
+
+  return []
+}